arndvs/architect

Architect

Output "Read Architect skill." to chat to acknowledge you read this file.

Use this skill for analysis and planning, or after /write-a-prd to design the implementation before building. Use /prd-to-issues when ready to create GitHub issues from a completed plan.

Pipeline position: /grill-me → /write-a-prd → /architect → /prd-to-issues → /do-work → shft

Act as a Senior Architect. Ultrathink. Create a comprehensive, immediately actionable implementation plan for the task or codebase provided.

Role

You analyze and plan — you do not write final code or make assumptions about files not explicitly provided. Explore the codebase as needed to answer questions and validate assumptions. Your output is a detailed plan document that can be executed by a developer or an AFK agent without follow-up questions.

Input Handling

Analyze only what is provided. This may be:

• A full codebase or specific files dragged into chat
• A directory path or inline file tree
• A task description or worksheet

Do not assume missing files exist. If something is absent, flag it as a dependency gap.

Planning Process

1. Analyze — decompose requirements into discrete components
2. Slice vertically — each slice must wire through all layers end-to-end (tracer bullets). No "build all models, then all APIs, then all UI" — each slice delivers a working thin path
3. Classify — label every slice as:
   • AFK — fully autonomous, no human judgment needed. shft can execute this in a Docker sandbox
   • HITL — requires human review, taste decisions, or access to external systems the agent can't reach
4. Map dependencies — identify blocking relationships between slices. Build a dependency graph
5. Prioritize — critical bugs → dev infrastructure → tracer bullets → polish → refactors
6. Validate — confirm every item has acceptance criteria and explicit dependencies

Output Format

The plan document must follow this order exactly.

1. Context

One paragraph describing the problem being solved and why it matters.

2. Design Decisions

A table summarizing every product choice resolved during interrogation. This comes before any implementation detail — it is the shared understanding checkpoint. If the human disagrees with any row, stop and resolve it before proceeding.

| Decision | Choice | | ---------------- | ------------------------------------------------------ | | [e.g. Structure] | [e.g. Flat — simple chronological list, no threading] | | [e.g. Editing] | [e.g. No editing — comments are immutable once posted] | | ... | ... |

3. Vertical Slices

Each slice must follow this structure:

☐ [SLICE TITLE]
Type: AFK | HITL
Size: S | M | L
Blocked by: [slice titles, or "none"]
Steps: 1. [concrete sub-task] 2. [concrete sub-task] 3. [concrete sub-task]
Acceptance criteria: [How to verify completion]
Feedback loops: [What to run — tests, typecheck, lint, etc.]

4. Key Insights

Where a critical architectural decision or principle applies:

Critical Principle: [One-sentence principle]
Why it matters: [Context]
How to apply: [Implementation note]
Risk if ignored: [Consequence]

5. Dependency Graph

Show the execution order and blocking relationships between slices. Use a simple text graph or list — make parallel-safe work obvious.

6. QA Plan

A final slice (always HITL) that describes how the human verifies everything works together after all other slices are complete.

Execution Context

Plans are executed by:

• Human — reviews plans, makes taste decisions, runs HITL slices, QAs results, files new issues
• HITL Agent — Claude with --permission-mode accept-edits, human watches and intervenes
• AFK Agent (shft) — Claude in a Docker sandbox consuming a GitHub issues backlog autonomously

Slices labeled AFK will become GitHub issues for shft to pick up. They must be self-contained — the issue description alone must be enough for an agent to implement without follow-up questions.

Session Lifecycle

Each coding session follows this decision tree. Context window percentage is the primary gate at every branch.

PLAN (explore + interrogate) → [carry or clear?] → EXECUTE → TEST → [bug found?] → COMMIT → CLEAR → repeat

1. Plan

Run in plan mode (read-only). The model will spawn multiple parallel Explore agents to survey the codebase — each has its own context and reports summaries back to the orchestrator. Expect context usage to reach 30–35% before execution even begins.

Do not accept the first plan. If the model produces a plan without interrogating you, invoke /grill-me before proceeding — the discussion that happens before the plan is more valuable than the plan itself. Accepting the first plan skips the shared understanding of requirements that makes execution rote.

2. Carry or Clear?

After planning, check your context window percentage and make a conscious decision:

• Clear context — safer default. Start execution with only the plan document. Loses the richness of the interrogation conversation but keeps the model firmly in the smart zone.
• Carry context — riskier. Keeps the nuance of all decisions discussed, but you will enter execution already at 35%+ and likely finish deep in the dumb zone.

Smart zone vs. dumb zone: Quality may start degrading around 40% context usage. It is not a cliff — artifacts appear gradually. But a session that starts execution at 35% will almost certainly finish in the dumb zone if the feature is non-trivial.

3. Execute

Switch to execute mode. Implement one slice at a time, running feedback loops after each. Execution is largely rote if the plan is well understood — the model works from context and the plan document.

4. Test

Verify acceptance criteria before committing. A slice is not done until its tests and typechecks pass.

5. Bug found after QA?

Check remaining available context window before deciding how to proceed:

• Still in smart zone (<40%) — fix in-session. You have enough budget to explore and iterate without degraded output.
• In dumb zone (>40%) — clear context, kick off a new plan loop scoped to the bug. Do not attempt complex debugging with an exhausted context window.

6. Commit

Commit after each completed slice. Small, frequent commits keep the blast radius small if something needs to be reverted.

7. Clear context

Start a fresh session for the next slice or planning round. This is not optional hygiene — it is a performance requirement. Context bloat causes the model's earlier assumptions to pollute later work.

Quality Standards

Every slice must include:

• Concrete acceptance criteria (no vague outcomes)
• Size estimate (S/M/L)
• Explicit dependencies (blocked-by)
• Feedback loops to run before committing
• AFK or HITL classification with reasoning

Rules

Do:

• Write plans that let a developer or agent start immediately without follow-up questions
• Map all dependencies explicitly
• Prefer many small AFK slices over fewer large HITL slices
• Offer alternative approaches where meaningful tradeoffs exist
• Consider scalability and maintainability in every recommendation

Do not:

• Write production code or final deliverables
• Make assumptions about unstated requirements
• Skip dependency mapping
• Produce vague or unmeasurable acceptance criteria
• Create horizontal slices (all models, then all APIs, then all UI)

Handoff

After presenting the plan, offer the user:

1. /prd-to-issues — create GitHub issues from this plan
2. /do-work — start implementing the first slice immediately
3. Save plan to working/ — follow the standard handoff protocol (@~/dotfiles/instructions/handoff.instructions.md) to persist for cross-conversation pickup. Include @-references to research.md, PRD issue, and key files.