feat: Archie Studio MVP (internal 3-tab local app) by gbrbks · Pull Request #100 · BitRaptors/Archie

gbrbks · 2026-06-12T13:18:42Z

What

Archie Studio — an internal-only experimental "software factory" app in studio/ at the repo root. A local web app you point at one project, with three tabs:

Product — markdown reader for PRD files (docs/prd/ or --prd <path>): collapsible file tree, GFM rendering, Obsidian-style [[wikilinks]] (basename resolution, shortest-path collisions, segment-boundary-safe path targets), YAML frontmatter shown as metadata chips, refetch-on-focus so Obsidian edits appear when tabbing back.
Architecture — the existing archie-viewer LocalPage mounted natively (blueprint sections, Mermaid, generated-files browser, rule adopt/reject all work unchanged).
Workflow — deliberate empty-state placeholder.

How

studio/server.py (zero-dep Python 3.9+) subclasses the handler from archie/standalone/viewer.py — all viewer API endpoints inherited; studio adds only GET /api/prd/tree and GET /api/prd/file (traversal-guarded, symlink-safe, md-only). Default port 5848 so it runs alongside archie-viewer on 5847.
studio/frontend/ (React 18 + Vite 6 + Tailwind 3, same dep versions as the viewer) imports viewer components via an @ alias pointed at npm-package/assets/viewer/src — zero duplication, build-time (loud) breakage on viewer refactors. Supporting config: tsconfig wildcard paths fallback, vite resolve.dedupe, viewer tailwind config as preset, scoped CSS shim offsetting the viewer's fixed sidebar past the studio icon rail.

Shipping safety

Nothing under npm-package/, archie/ (read-only import), scripts/, or .claude/ is touched — verified per-commit and on the final diff. verify_sync.py passes. Studio is not installed by the npm package and not referenced by manifest_data.py.

Verification

996 Python tests pass (main: 980; +16 in tests/test_studio_server.py: PRD helpers, traversal guard, endpoints, inherited-viewer-endpoint contract, SPA fallback). Server verified working on real Python 3.9.6.
15 vitest tests (frontmatter parser, wikilink resolver/transform).
Headless-browser verification of the built app: tree navigation, wikilink click-through, frontmatter chips, GFM task lists, rapid-click race tests, blueprint rendering on a real fixture (decisions, product laws, components, data models), viewer Files tab, tab round-trips, and all empty states (no PRD folder, no .archie/, fetch errors with retry).
Every task went through spec-compliance + code-quality review with fixes applied (fetch races, symlink edge cases, react-markdown v9 URL sanitizer, CSS shim scoping).

Run

cd studio/frontend && npm install && npm run build
python3 studio/server.py /path/to/project [--prd docs/prd] [--port 5848]

Design doc: docs/plans/2026-06-12-archie-studio-design.md (local, docs/plans/ is gitignored).

Generated with Claude Code

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Replaces the ArchitectureTab stub with the full archie-viewer local inspector. LocalPage has no router dependencies and fetches relative /api/* paths, which resolve against the studio server's inherited viewer endpoints. Two supporting changes were genuinely required to mount it: - vite.config.ts: resolve.dedupe pins the viewer tree's bare imports (lucide-react, mermaid, ...) to studio's node_modules. Viewer sources live outside the studio project root, so Rollup's node-resolution walk from npm-package/assets/viewer/src finds no node_modules and the build fails. Mirrors the existing "*" paths fallback in tsconfig.json that solves the same problem for tsc. - ArchitectureTab.tsx carries a scoped CSS shim: the viewer's sidebar is fixed inset-y-0 left-0 z-50, which pins to the viewport and covered the studio's 3.5rem icon rail, making rail links unclickable on this tab. The shim shifts the viewer's fixed chrome right by the rail width on lg+ and widens the content margin to match. Verified in the built app: blueprint sections (Key Decisions, Product Laws, Components, Data Models) render, empty state renders on a project without blueprint.json (/api/bundle 404 handled), and rail navigation between /product and /architecture works both ways with no new console errors. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The previous .studio-arch-tab main selector (0,1,1) also matched the NESTED <main ml-3> elements GeneratedFilesBrowser and FolderClaudeMdsBrowser render inside ReportPage's layout main, beating their .ml-3 (0,0,1) and shoving the Files-tab content ~21.5rem right on lg+ screens. Target main.min-h-screen, which only the layout main carries. Also documents the accepted transient skeleton underlap (its content sibling is a div with lg:ml-64, not a main) and notes that the vite.config dedupe list must track the viewer package.json deps. Verified in the built app against a fixture with generated files: the viewer's Generated Files browser renders its markdown card at the normal offset (inner main margin-left 12px, not 344px) while the Blueprint view keeps the shifted layout (344px margin, sidebar at x=56) and the studio rail stays clickable. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

vercel · 2026-06-12T13:18:51Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
archie	Ready	Preview, Comment	Jun 16, 2026 8:43am
archie-viewer	Ready	Preview, Comment	Jun 16, 2026 8:43am

No project path on the CLI now opens a folder-picker page instead of erroring: the server starts in picker mode, GET /api/fs/list browses directories (with .archie/prd badges), POST /api/project swaps the live handler class to the chosen project (ThreadingHTTPServer instantiates handlers per request, so the swap needs no restart). A rail button switches projects later. studio/run.sh installs deps and rebuilds the SPA only when sources are newer than the build. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…picker The Product tab now combines PRD documents from multiple sources instead of a single folder: explicit picks (--prd flag and folders added via the new Add PRD folder browser, persisted per project in ~/.archie/studio.json so target repos are never written to), the convention folders docs/prd/ and prd/ (all markdown), and auto-detected folders anywhere in the project containing PRD-named files like plan-audit.prd.md (only those files; 'prd' must be a filename token, so comprd.md does not match). Detection is a bounded walk (depth 4, 3000-dir cap, viewer skip-set) so monorepos stay fast. Sources nested inside an earlier source are deduped. /api/prd/tree returns a sources list, /api/prd/file requires the source root (validated against the registered set), and POST /api/prd/source adds a folder at runtime. The folder browser is extracted from ProjectPicker into a shared FolderBrowser component; the empty state gains a Choose PRD folder button. Selection and wikilink targets use sourceIndex/relPath virtual paths so equal relative paths across sources cannot collide. Verified in a headless browser against a real project whose PRDs live in @docs/ — previously showed 'No PRD folder found'. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

A server process predating the multi-source change answers /api/prd/tree with the old shape, which left the new frontend spinning on Loading forever (user-reported). Three fixes: the tree loader now fails loudly with a restart hint on shape mismatch; the server starts viewer.py's auto-reload watcher (--no-reload to disable) so a git pull re-execs the running process; and main() no longer feeds the first computed source back in as the explicit seed, which promoted detected folders like @docs to all-markdown mode. Source derivation extracted to initial_prd_state() with a wiring regression test. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

PRD documents with ```mermaid fences now render through the viewer's MermaidDiagram component (themed, lazy-loaded, falls back to showing the source with an error banner on invalid syntax) instead of a highlighted code block. Detection happens in the pre renderer via the hast node's language class, so rehype-highlight stays untouched for real code blocks. Browser-verified on a real project: a 3-subgraph flowchart plus a doc with 16 mixed diagrams (flowchart, mindmap, state, sequence) all render as SVG with zero console errors; inline code, tables, and non-mermaid blocks unaffected. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Each auto-detected PRD folder now contributes two sidebar sections: the PRD-named files (expanded) and the folder's other markdown (collapsed by default, 'other docs' chip, hidden when empty). Section headers are collapsible toggles. The companion shares the detected source's root, so file fetch validation and wikilink resolution cover it with no new endpoints; CLI startup labels skip companions to avoid '@docs, @docs'. Browser-verified on a real project: 3 PRDs in the expanded section, 14 other markdown files in the collapsed companion, both toggles work, companion files render, zero console errors. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…aude/commands ignore convention Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…l + source install) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat(studio): development studio — issue tracking + agentic dev loop

gbrbks and others added 17 commits June 12, 2026 13:19

chore(studio): ignore frontend build output

91a3856

feat(studio): server PRD helpers (resolve, tree, traversal-guarded read)

35db211

feat(studio): HTTP handler with PRD endpoints atop inherited viewer API

696c2ab

feat(studio): server CLI with port fallback and dist preflight

1956359

fix(studio): harden PRD helpers against filesystem edge cases

0f9d27a

feat(studio): frontend scaffold with @-alias into viewer source

1db8352

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

fix(studio): scaffold review fixes (error passthrough, config docs)

121bb53

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

feat(studio): minimal YAML frontmatter parser

78f29a4

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

feat(studio): Obsidian-style wikilink resolver and transform

4a4f473

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

fix(studio): wikilink path matching respects segment boundaries

1b29c7b

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

feat(studio): app shell with icon rail, routes, workflow placeholder

493bee3

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

fix(studio): review polish (lib edge cases, shell a11y, catch-all route)

3bcd4c7

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

feat(studio): product tab with PRD tree, wikilinks, frontmatter chips

7010028

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

fix(studio): product tab fetch races and robustness

e5c324d

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs(studio): README with run/develop instructions

8bad0ef

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

fix(studio): handle null-byte paths in PRD file reads

3ca9339

vercel Bot deployed to Preview – archie June 12, 2026 14:27 View deployment

vercel Bot deployed to Preview – archie-viewer June 12, 2026 14:27 View deployment

vercel Bot deployed to Preview – archie June 12, 2026 16:54 View deployment

vercel Bot deployed to Preview – archie-viewer June 12, 2026 16:54 View deployment

vercel Bot deployed to Preview – archie-viewer June 12, 2026 19:08 View deployment

vercel Bot deployed to Preview – archie June 12, 2026 19:08 View deployment

vercel Bot deployed to Preview – archie-viewer June 12, 2026 19:16 View deployment

vercel Bot deployed to Preview – archie June 12, 2026 19:16 View deployment

vercel Bot deployed to Preview – archie-viewer June 12, 2026 19:21 View deployment

vercel Bot deployed to Preview – archie June 12, 2026 19:21 View deployment

vercel Bot deployed to Preview – archie-viewer June 12, 2026 19:31 View deployment

vercel Bot deployed to Preview – archie June 12, 2026 19:31 View deployment

Update .gitignore

d067383

vercel Bot deployed to Preview – archie-viewer June 12, 2026 19:33 View deployment

vercel Bot deployed to Preview – archie June 12, 2026 19:33 View deployment

csacsi and others added 18 commits June 15, 2026 07:39

docs(studio): design spec for archie development studio

d37a89f

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(studio): implementation plan

323c628

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat(studio): next subcommand with Ralph priority

6e9ba63

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat(studio): frontmatter parser + status constants

1e54055

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat(studio): ticket discovery + id allocation

73c6f63

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat(studio): derived INDEX.md generation

18dce97

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat(studio): init scaffold with template + workflow doc

fcac8cf

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat(studio): idempotent AGENTS.md pointer patch

87a9433

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat(studio): new-ticket subcommand

08c9d2d

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat(studio): move subcommand with status validation

e0ece16

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat(studio): CLI entry point dispatch

ea64805

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

fix(studio): anchor status rewrite to frontmatter + collision guard

241c382

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat(studio): prompt bodies for setup/issue/work

7e0ca21

feat(studio): command routers for studio/issue/work

e30dbde

chore(studio): untrack generated command shims + prompts; restore .cl…

df164f6

…aude/commands ignore convention Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

chore(studio): sync studio assets + installer references

d2e25fc

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

fix(studio): register studio.py in _STANDALONE_SCRIPTS (Codex approva…

0867b5d

…l + source install) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Merge pull request #101 from BitRaptors/feature/development-studio

5e66a53

feat(studio): development studio — issue tracking + agentic dev loop

vercel Bot deployed to Preview – archie-viewer June 16, 2026 08:43 View deployment

vercel Bot deployed to Preview – archie June 16, 2026 08:43 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Archie Studio MVP (internal 3-tab local app)#100

feat: Archie Studio MVP (internal 3-tab local app)#100
gbrbks wants to merge 42 commits into
mainfrom
feature/studio-mvp

gbrbks commented Jun 12, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jun 12, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

gbrbks commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

How

Shipping safety

Verification

Run

Uh oh!

vercel Bot commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

gbrbks commented Jun 12, 2026 •

edited

Loading

vercel Bot commented Jun 12, 2026 •

edited

Loading