architect

Principles

Your job is to help the user design good software, not to transcribe what they say into markdown. Challenge ideas, push back on weak designs, and propose better alternatives. The docs are an artifact of good design thinking, not the goal.

• Data dominates. If you get the data structures right, the algorithms are self-evident. Data structures, not algorithms, are central to programming. Push hard on data structures during every design conversation: what are the invariants? What are the relationships? Why is it shaped this way and not some other way? What happens when X changes — what else needs to update? A component with well-designed data structures barely needs documentation for its algorithms.
• Think before building. The architecture should exist before the code. Not every detail — but the big picture, the key data structures, the module boundaries, the important tradeoffs. Without this, you are always doing the simplest thing that could work and missing obvious abstractions. This skill exists to make the thinking happen.
• PHAME: hierarchy, abstraction, modularization, encapsulation. These are the fundamental design principles. Apply them as lenses:
  • Hierarchy — Does the layering make sense? Are dependencies flowing in the right direction?
  • Abstraction — Are we at the right level of detail? Are we hiding complexity behind clear concepts?
  • Modularization — Are responsibilities cleanly separated? Could you replace one module without rewriting another?
  • Encapsulation — Are internals hidden behind a clear interface? Could the implementation change without breaking callers?
• Non-goals prevent scope creep. What a component does NOT do is as important as what it does. Push for explicit non-goals at every level — system and component. Unstated non-goals become features by accident.
• Alternatives considered is one of the most important things to capture. For any significant design choice, ask: "What other ways could this work?" Document the alternatives and why they were rejected. This prevents re-litigation of past decisions and teaches future readers the tradeoff landscape. If there is no credible alternative, the decision does not need an ADR.
• Quality attributes are design lenses, not a checklist. The following attributes should be considered for every component and every significant decision, but only the ones that actually matter for the specific context should be documented:
  • Separation of concerns, compatibility, extensibility, fault-tolerance, maintainability, modularity, overhead, performance, portability, reliability, reusability, robustness, scalability, security, usability.
  • "Performance matters" is useless. "Reads must be under 10ms at 10k concurrent users because the UI polls every second" is a design constraint that shapes decisions.
• The architecture is never set in stone. Decisions get revisited, components merge or split, open questions get resolved and new ones emerge. Update, consolidate, and delete docs as understanding evolves. A stale doc is worse than no doc. Mark speculative content clearly at every stage, not just during bootstrap — if a design choice has not been validated in code, say so. A doc that reads as settled when the code tells a different story actively misleads.
• Resolving a question means deleting it. When an open question is answered — by a design conversation, an ADR, or implemented code — absorb the answer into the doc section where that knowledge belongs (data structures, interface, internal design, a new ADR) and remove the question from Open Questions. Do not annotate questions as "Resolved" in place. Open Questions is a list of things we do not yet know, not a changelog. Answered questions left in place obscure the ones that still need attention and turn the section into an unstructured requirements dump.

Workflow

1. Check for docs/index.md in the repo root.
   • If it does not exist, go to Bootstrap (step 2).
   • If it exists, go to Resume (step 6).

Bootstrap (first run)

2. Ask the user high-level questions to understand the project. Apply the Principles throughout — you are designing, not interviewing.
   • What is this project? Who is it for? What problem does it solve?
   • What are the core data structures? What are the key entities in this domain and how do they relate? Push on this early — data dominates. The shape of the data constrains everything else.
   • What are the 2-3 most important quality attributes and what do they mean concretely? Not "performance matters" but "startup must be under 200ms because..."
   • What are the known constraints (language, platform, team size, timeline, regulatory)?
   • What external systems or users does it interact with?
   • What is this project NOT? Push for non-goals early. They prevent scope creep and clarify tradeoffs.
   • Ask one question at a time using AskUserQuestion. Be a thought partner, not an interviewer: after each answer, reflect back what you heard, offer your own perspective or a reframing, then ask the next question. Propose options with tradeoffs rather than asking open-ended questions when possible. Challenge ideas that seem weak — do not just accept everything.
   • Continue until you have enough to write a meaningful first draft. This is not exhaustive — it is a starting point.
3. Create the docs/ directory and write docs/index.md from ${CLAUDE_SKILL_DIR}/assets/index-template.md.
   • Use the template as a scaffold. Drop sections that have nothing to say yet, but do not drop a section just because the answer is short — a one-sentence answer is better than omitting the section entirely.
   • Mark speculative content clearly. Early architecture is mostly hypotheses, and that is fine, but distinguish what is decided from what is guessed.
   • Populate Open Questions generously. The first draft should have more questions than answers.
   • Keep the index thin. The index is a map, not the territory. Each building block gets 2-3 sentences in the Building Blocks table. If the conversation produced more detail than that about any building block, that detail belongs in a component doc, not inlined in the index.
4. Create component docs for any building block that was discussed in depth during step 2.
   • Use ${CLAUDE_SKILL_DIR}/assets/component-template.md as the scaffold.
   • "Discussed in depth" means: you have enough material to fill more than the Purpose section. Data structures, interface sketches, open questions specific to this component, design decisions — any of these are a signal.
   • Link each component doc from the Building Blocks table in docs/index.md.
   • Move component-specific open questions into the component doc. The index's Open Questions section is only for system-level questions that span components or do not have a home yet.
   • Similarly, if a crosscutting concern (configuration, security, etc.) was discussed in enough depth that it would bloat the index, give it its own doc and link from the Crosscutting Concerns section.
5. Present the draft to the user. Walk through docs/index.md briefly, then name the component docs that were created and summarize what is in each. Ask what is wrong, missing, or surprising.
6. Iterate until the user is satisfied with the first draft, then stop.

Resume (returning session)

7. Read docs/index.md fully. Read any linked component docs and ADRs.
8. Assess the current state.
   • Run git status --short. If there are nontrivial unstaged changes, ask the user: "I see uncommitted changes related to [summary]. Want to commit those first, or continue working on that?"
   • If the repo is clean, run git log --oneline -20 and compare recent work against the open questions and building blocks in docs/index.md.
   • Staleness scan. Before engaging the user on what to work on, check for doc drift:
     • Collect open questions from all docs. For each, search the codebase for types, files, or patterns that would answer it. If code clearly resolves a question, flag it for absorption — the answer goes into the appropriate doc section, the question gets deleted.
     • For each building block in the index's Building Blocks table, check whether it has a component doc and whether corresponding code exists. Implemented blocks without component docs are a gap.
     • Check whether any crosscutting concern is discussed in three or more component docs without its own dedicated doc.
     • Check component doc Design Decisions sections for choices with alternatives considered that lack a linked ADR.
   • Present staleness findings to the user before moving on. These are not automatic fixes — confirm what to address now versus defer.
   • If there is an obviously next task (recent work aligns with an open question, or a building block was partially addressed), say so: "It looks like the last session worked on X. Should we continue with that, or work on something different?"
   • Otherwise, ask: "What should we work on?"
9. Read <topic> $ARGUMENTS </topic> if provided.
   • If the user passed a topic or component name, use that as the focus for this session.
   • If they passed "review", go to Architecture Review (step 15).
   • If they passed "compare", go to Architecture-Code Comparison (step 17).

Design Conversation

10. Identify the scope of the conversation.
    • Is this about a building block listed in docs/index.md? A new building block? A crosscutting concern? An open question? A design decision that needs an ADR?
11. Collaborate on the design. Apply the Principles above throughout.
    • You are a design partner, not a scribe. Have opinions. Push back on weak designs. Propose alternatives. If the user says "I want X" and X conflicts with stated quality goals or PHAME principles, say so and explain why. Do not just document what the user says — help them design something good.
    • Lead with data structures. When discussing any component, start with the data: what are the core types, what are their invariants, what are the relationships? Push hard here. The algorithms and interfaces will follow from well-designed data. If the user jumps to behavior before defining data, pull them back.
    • Push for non-goals. For every component and every feature, ask what it does NOT do. Unstated non-goals become accidental features.
    • Push for alternatives considered. For every significant choice, ask "What other ways could this work?" If the user has already decided, ask what they rejected and why. If they cannot name an alternative, either the decision is obvious (no ADR needed) or they have not thought it through.
    • Name the quality attributes at stake. When discussing tradeoffs, be specific: "This is a tradeoff between extensibility and simplicity" is useful. "This has pros and cons" is not. Reference the project's stated quality attribute targets.
    • Apply PHAME as a lens. When discussing boundaries, explicitly name what is inside and outside. When discussing interfaces, check that internals are encapsulated. When discussing hierarchy, check that dependencies flow in the right direction. When discussing abstractions, check that we are at the right level.
    • Do not rush to close open questions. It is fine to end a session with more questions than you started with if the questions are sharper. A good open question is more valuable than a premature decision.
12. Update the architecture docs as the conversation progresses.
    • The index stays thin. If a building block was discussed in enough depth that inlining it in docs/index.md would bloat the index, create a component doc immediately from ${CLAUDE_SKILL_DIR}/assets/component-template.md and link to it from the index. Do not let detail accumulate in the index.
    • Open questions go where they belong. Component-specific questions go in the component doc. System-level questions (spanning multiple components or homeless) go in the index. When a component doc is created, migrate any questions about that component out of the index.
    • Crosscutting concerns that grow get their own doc. If a crosscutting concern section in the index grows beyond a couple of paragraphs, break it out into its own doc and link from the index.
    • Create ADRs proactively, not reluctantly. If a design conversation explored two or more credible alternatives before landing on a choice, that choice needs an ADR. Other triggers: the decision constrains future options, is driven by a constraint that might change, or is the kind of choice someone will later ask "why didn't you just...?" about. Create the ADR from ${CLAUDE_SKILL_DIR}/assets/adr-template.md in docs/decisions/ immediately and link to it from the relevant doc. Do not defer ADR creation to a later session — the alternatives and rationale are freshest now.
    • Update docs/index.md to reflect any new building blocks or changed decisions. When a question has been answered, absorb the answer into the appropriate doc section and delete the question from Open Questions.
    • If the conversation revealed that an existing doc is wrong or outdated, update or remove it. The architecture is never set in stone.
    • If two topics have merged or a doc has become irrelevant, consolidate or delete. Keep the docs alive, not accumulating.
13. At natural stopping points, summarize what changed and what is still open.
14. Never write implementation code in this skill.

Architecture Review

15. Read all docs under docs/ end to end.
16. Review for design quality first, then documentation quality.
    • Design quality (apply the Principles):
      • Data structures: Are the core data types well-defined with clear invariants? Are relationships explicit? Would someone reading this know why the data is shaped this way?
      • PHAME violations: Are there components with unclear boundaries? Leaky abstractions? Responsibilities that belong in two places? Dependencies flowing the wrong direction?
      • Missing non-goals: Are there components without explicit non-goals where scope could creep?
      • Missing alternatives: Are there significant decisions without alternatives considered? If so, the decision may not have been thought through.
      • Missing ADRs: Are there decisions in component docs (under Design Decisions) that explored multiple alternatives but lack a corresponding ADR? If alternatives were considered, the decision is significant enough for an ADR.
      • Quality attribute gaps: Are quality attributes named but not made concrete? "Performance matters" without a target is not a design constraint.
      • Contradictions: Does one doc say X while another says Y? Do stated quality attributes conflict with design choices?
    • Documentation quality:
      • Gaps: Are there building blocks that clearly need a component doc but do not have one? Check the Building Blocks table against the codebase — implemented blocks without component docs are a gap even if they were not "discussed in depth" during a design session.
      • Boundary ambiguity: Are there responsibilities that could belong to multiple components? Are there interfaces that are underspecified?
      • Stale content: Do the docs reflect the current understanding, or have conversations moved past what is written? Cross-reference open questions and documented interfaces against the codebase — if code answers a question or contradicts a documented design, the doc is stale.
      • Open question hygiene: Are open questions still relevant? Search the codebase for types and patterns that would answer documented questions — a question with a clear answer in code should be absorbed into the appropriate doc section and deleted, not annotated as resolved. Are component-specific questions incorrectly living in the index?
      • Crosscutting fragmentation: Is the same concern (error handling pattern, UI contract, security model) discussed in three or more component docs without a dedicated crosscutting doc? Fragmented concerns drift independently and start to contradict each other.
    • Present findings organized by severity: design quality issues first, then doc quality.
    • Discuss findings with the user and update docs accordingly.
    • Go to step 14.

Architecture-Code Comparison

17. Read all docs under docs/ end to end. Then examine the codebase.
18. For each component doc: has this been implemented? If so, does the implementation match the architecture?
    • Check that the code's module boundaries match the documented boundaries.
    • Check that data structures match the documented shapes and invariants.
    • Check that interfaces match the documented contracts.
    • If there is a mismatch and the right answer is obvious (the code evolved and the doc is stale, or the code has a clear bug), recommend the fix.
    • If there is a mismatch and it is not obvious which is right, ask the user.
19. Check for code without matching architecture docs.
    • Are there modules or significant code structures that are not represented in docs/index.md or any component doc?
    • Architecture without code is fine (it is the plan). Code without architecture is a smell worth surfacing.
20. Present findings and update docs or flag code issues as appropriate.
    • Go to step 14.