hellblazer/architecture

Architecture Skill

Delegates to the architect-planner agent.

Model Selection

Default: sonnet. Escalate via model parameter on the Agent tool:

| Task Shape | Model | When | |-----------|-------|------| | Single-module design, extension of existing pattern | sonnet (default) | Most architecture work | | Multi-phase, novel architecture, or system-wide redesign | opus | Greenfield, cross-cutting concerns |

Code Navigation

REQUIRED SUB-SKILL: Use nx:serena-code-nav for symbol-level architecture discovery. Combine with nx search --hybrid for semantic discovery — Serena for precision, nx search for conceptual queries.

• Map system structure: get_symbols_overview for class/interface inventories without reading files
• Find architectural patterns: find_referencing_symbols to trace abstraction usage across the codebase
• Understand module boundaries: find_referencing_symbols to track cross-module calls
• Interface analysis: type_hierarchy to see full implementation tree
• Serena for precision, nx search for semantic discovery

Architecture Discovery Workflow

1. nx search --corpus code --hybrid (30-50 results) for semantic discovery
2. get_symbols_overview to map key classes in discovered files
3. type_hierarchy to trace abstraction patterns
4. find_referencing_symbols to understand cross-module usage
5. Synthesize findings with `mcp__plugin_nx_sequential-thinking__sequentialthinking`
6. Design architecture with clear boundaries

When This Skill Activates

• Before implementing complex features requiring architecture design
• When planning multi-step implementations
• Before major refactoring efforts
• When system design decisions are needed
• When establishing module boundaries or interfaces

Pipeline Position

strategic-planner -> nx_plan_audit -> architect-planner -> developer

Pre-Dispatch: Seed Link Context

Before dispatching the architect-planner agent, seed T1 scratch with link targets so the auto-linker can create catalog links when the agent stores findings:

1. If the task references an RDR (pattern RDR-\d+) or a known document, resolve it: mcp__plugin_nx_nexus-catalog__search(query="RDR-NNN or document title")
2. Check T1 scratch for rdr-planning-context
3. Write link context to scratch:

   mcp__plugin_nx_nexus__scratch(action="put", content='{"targets": [{"tumbler": "<resolved-tumbler>", "link_type": "relates"}], "source_agent": "architect-planner"}', tags="link-context")
   

4. If no RDR/document reference found, skip seeding (the auto-linker handles empty context gracefully)

Agent Invocation

Use the Agent tool to invoke architect-planner:

## Relay: architect-planner

**Task**: [what needs to be done]
**Bead**: [ID] or 'none'

### Input Artifacts
- Files: [relevant files]

### Deliverable
Architecture design with execution plan

### Quality Criteria
- [ ] Component boundaries clearly defined
- [ ] Interfaces specified
- [ ] Execution plan created with beads

For full relay structure and optional fields, see RELAY_TEMPLATE.md.

Architecture Methodology

The architect-planner uses nx search --corpus code --hybrid for discovery (30-50 results), then mcp__plugin_nx_sequential-thinking__sequentialthinking:

1. Understand system architecture and integration patterns
2. Synthesize findings into architectural approach
3. Define component boundaries and interfaces
4. Create execution plan with beads
5. Identify risks and mitigations

Success Criteria

• [ ] All requirements addressed in design
• [ ] Component boundaries clearly defined
• [ ] Interfaces specified
• [ ] Execution plan created with beads
• [ ] Beads created for trackable work
• [ ] Risks identified with mitigations
• [ ] Ready for mcp__plugin_nx_nexus__nx_plan_audit validation (RDR-080)

Agent-Specific PRODUCE

• Architecture Designs: Store in nx T3 via store_put tool: content="# Architecture: {component}\n{design}", collection="knowledge", title="architecture-{project}-{component}", tags="architecture,design"
• Execution Plans: Store in nx T2 memory via memory_put tool: content="plan", project="{project}", title="plan-{component}.md", ttl="30d"
• Design Decisions: Store in nx T3 via store_put tool: content="# Decision: {topic}\n{rationale}", collection="knowledge", title="decision-architect-{topic}", tags="decision,architecture"
• Beads: Epic → Phase → Task hierarchy with /beads:dep add for dependencies
• Design Notes: Use T1 scratch for working notes during architecture analysis:
  • scratch tool: action="put", content="Design consideration: {note}", tags="architecture,design"
  • scratch_manage tool: action="flag", entry_id="<id>", project="{project}", title="architecture-notes.md"