{"slug": "proposal-for-to-architecture-skill", "title": "Proposal for /to-architecture skill", "summary": "A developer proposed a new skill for the to-architecture workflow that converts accepted specs into concrete implementation architectures. The skill instructs agents to read issue-tracker tickets, use codebase-design terminology, spawn sub-agents to gather evidence, and apply architectural principles like depth and locality. It aims to make module placement and interfaces deliberate rather than improvised.", "body_md": "| name | to-architecture |\n|---|---|\n| description | Design one implementation architecture for a spec and publish the approved design to its issue-tracker ticket. |\n| disable-model-invocation | true |\n\nTurn an accepted spec into one concrete implementation architecture. The design guides implementing agents so module placement, responsibilities, interfaces, and seams are deliberate rather than improvised. Aim for testability and AI-navigability through deep modules.\n\nThis skill extends the spec ticket with an architecture comment. It does not edit the ticket body, create tickets, change labels, or write files to the repository.\n\nResolve the spec ticket from the user's reference or the current conversation. If neither identifies it, ask for the ticket reference.\n\nRead the full ticket body and comments using the workflow in `docs/agents/issue-tracker.md`\n\n. Treat the ticket body as the behavioral spec. When revising an architecture, identify the existing architecture comment from its `## Implementation architecture`\n\nheading and content rather than creating a competing one.\n\nThe issue tracker should have been provided. If `docs/agents/issue-tracker.md`\n\nis missing, tell the user to run `/setup-matt-pocock-skills`\n\n.\n\nCall the Skill tool with \"codebase-design\". Use its terms **module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, and **locality** exactly throughout the proposal.\n\nRead `CONTEXT.md`\n\nand the ADRs relevant to the spec when they exist. Use the glossary's domain language to name modules and good seams.\n\nThen spawn a sub-agent to explore the affected codebase. Give it the spec and the relevant domain and ADR context. Tell it to call the Skill tool with \"codebase-design\", trace the current code paths, modules, interfaces, dependencies, and tests touched by every material requirement, and return a concise evidence report covering:\n\n- Requirement-to-module and file-path mapping\n- Current interaction flow, state ownership, side effects, and error handling\n- Existing interfaces, seams, adapters, and test surfaces\n- Relevant test locations and prior art\n- Architectural gaps and the scoped friction below, with supporting code references\n\nThe sub-agent gathers evidence rather than choosing the final architecture. Keep its exploration scoped to what is needed to fit this spec into the system; nearby friction matters only when it affects that design. The main agent should inspect additional code only to resolve missing or conflicting evidence before designing the proposal.\n\nWithin that scope, look for architectural friction that the feature would preserve or worsen:\n\n- Understanding one domain concept requires bouncing between many small modules\n- A module is shallow because its interface is nearly as complex as its implementation\n- Logic was extracted only for testability while bugs remain in how callers coordinate it\n- Coupled modules leak knowledge across their seams\n- Important behavior is untested or difficult to test through the current interface\n\nComplete this step when every material requirement in the spec has a known place in the current system or an identified architectural gap.\n\nChoose the architecture that best fits the spec and the existing system. Depending on the evidence, the proposal may deepen or change existing modules, add new modules, or do both.\n\nFor every proposed module change, establish:\n\n- The module's responsibility and why it belongs there\n- Its interface, including important invariants and error behavior\n- The seam at which callers and tests use it\n- Its dependencies and any real adapters\n- Ownership of state, validation, side effects, and failures\n- Its place in the end-to-end interaction or data flow\n- The relevant existing or intended file path\n\nApply the deletion test to existing modules considered for change and to proposed new modules. Prefer depth, locality, and leverage. Treat one adapter as a hypothetical seam and two adapters as evidence of a real seam; do not introduce an adapter solely to make mocking convenient. Respect existing ADRs; identify and explain any conflict the spec makes unavoidable.\n\nInclude structural prefactoring required to reach the design, stated as a target architectural change.\n\nConsider alternatives while reasoning, but present one coherent recommendation. If a material tradeoff cannot be resolved from the spec and codebase, discuss that decision with the user before completing the proposal.\n\nIf the user wants to explore alternative interfaces, use the `codebase-design`\n\ndesign-it-twice process, compare the alternatives, and still bring one recommendation forward for approval.\n\nComplete this step when every material spec requirement is assigned to a module and observable through a stated test surface.\n\nPresent the proposal in the conversation. Revise it with the user until they explicitly approve it.\n\nDo not publish exploratory alternatives or an unapproved proposal to the issue tracker. The architecture comment is the decision, not a transcript of the design discussion.\n\nPublish the approved design as a comment on the spec ticket using the configured issue-tracker workflow. If an existing comment contains the `## Implementation architecture`\n\nsection, update it when the tracker supports comment editing; otherwise publish a replacement that explicitly supersedes the earlier architecture comment.\n\nUse this structure:\n\n```\n## Implementation architecture\n\n### Design summary\n<The chosen architecture, why it fits the spec and existing system, and how it improves locality, leverage, testability, and AI-navigability.>\n\n### Modules and interfaces\n<Existing modules to change or deepen and new modules to add. Include relevant paths, responsibilities, interfaces, seams, dependencies, and adapters.>\n\n### Interaction flow\n<How control, data, state, errors, and side effects move through the modules.>\n\n### Testing architecture\n<The interfaces that form the test surfaces and relevant existing test locations or prior art.>\n\n### Required structural changes\n<Prefactoring or migration required by the design, or \"None\". Describe the architectural target state.>\n\n### Spec coverage\n<Map every material requirement or coherent requirement group to the module behavior that satisfies it.>\n\n### Constraints and conflicts\n<Relevant ADR constraints, unavoidable conflicts, or \"None\".>\n```\n\nFile paths are location anchors, not an exhaustive edit list. Keep the comment precise about ownership and interfaces while leaving private helpers, algorithms, line-level edits, and other low-level implementation choices to the implementing agent.\n\nFinish by returning the spec ticket reference and confirming that the approved architecture comment was published.", "url": "https://wpnews.pro/news/proposal-for-to-architecture-skill", "canonical_source": "https://gist.github.com/blizzy78/ad7d62551c425277e7fd3024d3240434", "published_at": "2026-08-20 21:24:23+00:00", "updated_at": "2026-08-21 04:43:36.531567+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents"], "entities": ["Matt Pocock"], "alternates": {"html": "https://wpnews.pro/news/proposal-for-to-architecture-skill", "markdown": "https://wpnews.pro/news/proposal-for-to-architecture-skill.md", "text": "https://wpnews.pro/news/proposal-for-to-architecture-skill.txt", "jsonld": "https://wpnews.pro/news/proposal-for-to-architecture-skill.jsonld"}}