jaisonerick/architect

Your task: produce a comprehensive implementation approach document and write it to the deliverable's Linear project as a Project Document titled Architecture. This is the PROJECT-LEVEL architecture — it covers decisions shared across ALL specs/versions in this project. Individual specs get their own architecture documents via /architect-version.

Linear contract

This skill writes to Linear via the bundled scripts in ${CLAUDE_PLUGIN_DIR}/scripts/linear/. They require LINEAR_API_KEY in the environment. If it isn't set, fetch it from 1Password before running scripts: export LINEAR_API_KEY="$(op read op://Environments/Linear/credential)".

Phase 0 — Resolve the target Linear project

The argument is one of:

• A Linear project URL or UUID — use directly.
• A free-text query — call search.js and present the top matches via AskUserQuestion.
• A path to a project briefing on disk (or no argument, with a briefing in CWD) — read the briefing's frontmatter for a Linear URL; if none, treat the briefing's title or folder name as a search term.

node "${CLAUDE_PLUGIN_DIR}/scripts/linear/search.js" --type project --query "<text>" --limit 5

Render results as <name> — <team keys> — <url> and let the user pick. If there are no matches, ask the user to provide the URL or run /plan first to create the project. Never guess — keep asking until the user confirms.

Once resolved, fetch the project and its existing documents:

node "${CLAUDE_PLUGIN_DIR}/scripts/linear/get-project.js" "<project-id>" --with-documents --with-issues

Record project_id, project_url, and check whether a document titled Architecture already exists. If yes, ask via AskUserQuestion whether to redo or revise.

Phase 1 — Load Knowledge-Base Context

The reasoning/context lives on disk:

1. Read the project briefing if accessible (path provided or referenced in the Linear project description's Context: line).
2. Look for surrounding files in the same folder: research notes, decisions, comms — anything that informs the architecture.
3. From the briefing's frontmatter or content, identify the project type (code, business/consulting, research, hybrid).
4. If the briefing is missing, ask the user to point at one or run /ideate first.

The briefing's project context (type, language, workspace, code repository) tells you what kind of architecture this needs.

Phase 2 — Identify Decision Points

Catalog every foundational decision needed. The categories depend on the project type.

For Code / Product Projects

• Language & Runtime — Programming language(s), version requirements, package management
• Web Framework — Backend API framework, frontend framework
• Data Storage — Primary database(s), caches, state storage
• Task Processing — Queue system, worker architecture, job patterns
• LLM & AI — LLM abstraction, embedding strategy, provider config (if applicable)
• External Services — Third-party APIs, integrations
• Pipeline Orchestration — How processing steps are defined and coordinated
• State Management — What's tracked where, incremental processing
• Real-time Communication — Live updates, webhooks, SSE
• Observability — Tracing, metrics, logging, cost tracking
• Frontend — UI framework, component library, data visualization
• Configuration — Settings management (files, env vars, runtime)
• Project Structure — Directory layout, module organization
• Setup & Deployment — How to install dependencies, configure, start, and deploy

Not every project needs all categories. Skip what's irrelevant.

For Business / Consulting Projects

• Delivery Structure — What gets delivered, in what order, in what format
• Document Organization — How deliverables are structured and where they live
• Tools & Resources — What tools, data sources, or reference materials are needed
• Stakeholder Communication — How updates, reviews, and approvals flow
• Quality Gates — What review/approval steps exist before delivery
• Dependencies — External inputs, access, or decisions needed
• Risk Mitigation — How identified risks are managed

For Research / Exploration Projects

• Research Methodology — How investigation will be conducted
• Source Strategy — What sources to use, how to evaluate them
• Output Format — Structure of the research output
• Analysis Framework — How findings will be organized and evaluated
• Tool Selection — Research tools, data collection methods
• Scope Management — How to handle scope expansion during research

For Hybrid Projects

Mix categories from the above as appropriate.

Phase 3 — Consult User

For each major decision, use AskUserQuestion to present:

• The decision to make
• 2-4 concrete options with trade-offs (include a comparison table when useful)
• Your recommendation and why

Group related decisions (2-3 per round) to keep the conversation efficient. Iterate until all major decisions are resolved.

Phase 4 — Write Architecture Document to Linear

Compose the architecture content as Markdown using the section template that fits the project type (see below), then write it to Linear:

# New document
cat <<'MD' | node "${CLAUDE_PLUGIN_DIR}/scripts/linear/create-document.js" \
  --project "<project-id>" \
  --title "Architecture"
<full markdown content>
MD

# Or, if revising an existing one (you have its <doc-id> from get-project.js):
cat <<'MD' | node "${CLAUDE_PLUGIN_DIR}/scripts/linear/update-document.js" "<doc-id>"
<full markdown content>
MD

Use a tempfile via Write to a /tmp/<project-name>/architecture.md location and pipe it to the script — this keeps the prompt clean and lets you re-run on failure.

For Code Projects — sections to include

1. Technology Stack — Table: Layer, Technology, Rationale
2. System Architecture — Diagram (ASCII/mermaid) showing components and data flow
3. Project Structure — Full directory tree with annotations
4. Configuration — Config file format, environment variables
5. API Routes — Endpoints grouped by domain (method, path, description)
6. Database Schemas — Full schema definitions with comments
7. Pipeline Architecture — Job flow, queue patterns, step transitions
8. State Management — Data store responsibilities, incremental processing
9. Observability — Instrumentation strategy, metrics, cost tracking
10. Key Design Decisions — Table: Decision, Choice, Why
11. Setup & Deployment — Exact commands, environment setup, prerequisites
12. Dependencies — Explicit dependency lists with version constraints

For Non-Code Projects — sections to include

1. Delivery Approach — How the project will be executed, what phases
2. Deliverable Structure — What gets produced, document templates, folder organization
3. Tools & Resources — What's needed, where to find it, access requirements
4. Communication Plan — How stakeholders stay informed, review cadence
5. Quality Framework — How deliverables are reviewed and validated
6. Key Decisions — Table: Decision, Choice, Why
7. Risk Register — Risk, Impact, Mitigation, Owner
8. Dependencies & Prerequisites — What's needed from outside the project

Writing Principles

• Show, don't tell. Include actual schemas, config examples, code patterns, directory trees, document templates — not descriptions of them.
• Rationale everywhere. Every choice should have a "Why" connected to project constraints.
• Concrete over abstract. Show actual queries, actual configs, actual document outlines.
• Diagrams for complex relationships. Use mermaid for architecture, data flow, sequences. Linear renders mermaid in documents.

Phase 5 — Cross-link with the knowledge base

If the project briefing on disk has a "Linear" or "Quick Links" section, append a link to the new Architecture document. If the project's Linear description does not start with Context: <path-to-briefing>, propose updating it via set-project-description.js. Confirm with the user before editing either side.

Phase 6 — Consistency Check

Before finalizing, verify:

• Every success criterion from the briefing has a corresponding component in the architecture
• Every deliverable has a clear production path
• No component references something not described in the architecture
• The architecture matches the project type (don't describe API routes for a research project)

Phase 7 — Final Review

Present a summary:

• Linear document URL (returned by create-document.js)
• Key decisions made and their rationale
• Any deferred decisions (and when they'll be resolved)
• Risks or concerns
• Suggested next step: "Run /plan to design the delivery roadmap, then /orchestrate <DIN-XXX> to execute each spec."

Ask for final sign-off.