From gg-senior-tools
Generate or harden a production-grade architecture.md from a PRD. Use this skill whenever the user wants to design a system architecture, create architecture.md, audit an existing architecture, or resolve TBDs in architectural decisions. Also trigger when the user says they are ready to build after a PRD is done, or asks "what should the stack look like". Gates gg-skill-specs — architecture must reach confidence ≥ 0.8 before specs can run.
How this skill is triggered — by the user, by Claude, or both
Slash command
/gg-senior-tools:gg-skill-architectureThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
An architecture that cannot drive `gg-skill-specs` without additional input is not done.
An architecture that cannot drive gg-skill-specs without additional input is not done.
The full output schema (sections 1–15 with templates) is in references/schema.md — read it when writing Phase 3.
| Mode | Trigger | What happens |
|---|---|---|
| Discovery | PATH only | Read PRD → adversarial review → write architecture.md |
| Enhancement | -f PATH -enh | Audit existing architecture.md → produce additive architecture-enhancement.md |
| Apply | -f PATH -apply | Enhancement + auto-resolve TBDs + re-validate in one pass |
| Autoupdate | -f PATH -update | Re-audit against current dep-tree.md / PRD-patched.md — refresh Agent Status Block only |
| Output | -o PATH | Custom output path for architecture.md |
All generated content must be written in English.
/gg-skill-prd -apply
↓
PRD-patched.md (confidence ≥ 0.8, ready_for_architecture: true)
↓
/gg-skill-architecture PRD-patched.md
↓
architecture.md (confidence ≥ 0.8, ready_for_specs: true)
↓
/gg-skill-specs N (per phase)
Pre-flight check: Before running, verify that PRD-enhancement.md (if it exists) has ready_for_architecture: true. If it is false, stop and tell the user:
⚠ PRD is not ready for architecture (ready_for_architecture: false).
Run: /gg-skill-prd -f PRD.md -apply first.
Before reading the PRD, load all available context silently:
| File | What to extract |
|---|---|
dep-tree.md | Existing modules, high-coupling zones, already-built components |
PRD-enhancement.md | confidence_score, phases_in_codebase, blocking_issues still open |
architecture.md | If it exists → Enhancement mode (see below) |
If architecture.md already exists and -enh / -apply was NOT specified:
⚠ architecture.md already exists at {path}.
Running Enhancement mode to avoid overwriting existing decisions.
Use -apply to auto-resolve TBDs, or pass -o to write a new file.
dep-tree.md usage:
[BUILT] = module already implemented → do not re-architect it[RISK] in related ADRsRead the PRD at $ARGUMENTS. Extract and internalize:
| PRD Section | What to extract |
|---|---|
| Executive Summary | Scale targets, success KPIs, constraints |
| Target Users | Concurrent users, device types, geography |
| MVP Scope | Features that drive architectural decisions |
| Feature Specifications | Data flows, real-time needs, async jobs |
| Technical Architecture (if present) | Stated stack choices, ADR-lite decisions |
| Data Models | Entities, relationships, critical constraints |
| Non-Functional Requirements | Latency, uptime, scale targets with values |
| Security & Compliance | Auth strategy, compliance requirements, threat model |
| Phase Roadmap | What must be built per phase |
If the file does not exist or is unreadable: stop and tell the user with the exact path tried.
Before writing a single line of architecture, run this internal review.
Adopt the gg-socrate posture: anti-sycophancy, steelman, no vagueness. Every weakness found must be resolved in the architecture — not noted and left open.
| Challenge | What it catches |
|---|---|
| "Is this DB choice driven by actual data access patterns, or familiarity?" | Cargo-culting |
| "What breaks at 10× current load — specifically, which component fails first?" | Premature scalability gaps |
| "Is this service boundary justified by team ownership or deployment independence, or just decomposition for its own sake?" | False microservices |
| "What is the single component whose failure takes down the entire system?" | SPOF not mitigated |
| "Which ADR says TBD without listing two alternatives and their trade-offs?" | Blocked architecture decisions |
| "Which component calls which — is any fan-out > 4?" | Coupling hot spots |
| "Is there a queue / async handoff here that could fail silently?" | Silent failure modes |
| "Does the auth strategy handle token revocation, not just issuance?" | Incomplete security design |
| "Which external dependency has no fallback strategy?" | Single external SPOF |
| "Is the data model normalized enough to avoid update anomalies, but not so normalized it creates N+1 query traps?" | Schema design issues |
For each core component, answer:
Rule: Do not proceed to Phase 3 with a SPOF that has no mitigation, a TBD ADR without alternatives, or an NFR without an architectural response.
Read references/schema.md for the complete output template (sections 1–15).
Output file: path specified by -o, or architecture.md in the same directory as the PRD.
The architecture is not complete until ALL of the following pass.
Structural completeness (6 criteria)
Decision quality (3 criteria)
[DECIDED] / [RECOMMENDED] / [TBD] — no unmarked choices[RECOMMENDED] contradicts a [DECIDED] from the PRD without an ADR explaining the divergenceNFR coverage (2 criteria)
Security (1 criterion)
Output of this gate (in chat, not in architecture.md):
## Architecture Validation
- ✅ Structural completeness: X/6 criteria
- ✅ Decision quality: X/3 criteria
- ✅ NFR coverage: X/2 criteria
- ✅ Security: X/1 criteria
[Any ❌ items listed with what's missing and how to fix]
confidence_score: 0.XX (threshold: 0.80)
[✅ Ready for /gg-skill-specs | ⚠ Resolve N blocking issues first]
-f PATH -enh)When an existing architecture.md is provided:
architecture-enhancement.md (additive only — never modify the original)Sections in order: header → Agent Status Block (Section 15 schema) → What Is Already Senior-Grade → Blocking Gaps → Should Fix → Accepted Weaknesses → Next Action Plan (ordered by blocking priority, ending with /gg-skill-specs 1 when all blocking gaps are resolved).
-f PATH -apply)Apply mode runs Enhancement → auto-resolves TBDs using FULL/SKELETON/BLOCKED source resolution → re-runs Validation Gate → loops until ready_for_specs: true or hits an unresolvable gap.
Source resolution (before any injection):
FOR EACH TBD / gap identified:
SOURCES (in priority order):
1. PRD-patched.md → most complete — use if PRD section covers it
2. PRD.md → fallback if PRD-patched not present
3. dep-tree.md → for component names and existing structure only
4. architecture.md → existing decisions (for Enhancement mode)
IF source found with full detail → quality: FULL
IF source only gives structure → quality: SKELETON → inject [TBD] placeholder
IF no source → quality: BLOCKED → skip, list for human input
Apply rules:
architecture.mdarchitecture-patched.md (or path from -o)<!-- injected by gg-skill-architecture -apply -->[TBD — requires owner input]After Apply output (in chat):
## Apply Mode — Result
Patched: {output path}
Passes: {N}
Before: {X}/12 ✅ ({blocking} blocking, {should} should-fix)
After: {Y}/12 ✅ ({blocking} blocking, {should} should-fix)
Patch report:
✅ Added (FULL): {section}, {section}, ...
⚠ Partial (SKELETON): {section} — [TBD] markers inserted
❌ Failed: {section} — reason: {no source | requires human input}
confidence_score: {before} → {after}
{IF ready_for_specs}
Next: /gg-skill-specs 1
{IF blocking_issues remain}
⚠ {N} blocking issues require human input — see above.
-f PATH -update)Re-audits the architecture against the current state of the codebase without rewriting any content.
What it reads:
architecture.md (or architecture-patched.md if present)dep-tree.md (current)PRD-patched.md (if present — checks for new NFRs or phases since last run)architecture-enhancement.md (if present — updates its Agent Status Block only)What it updates (YAML block only):
updated_at → current datetimedrift_from_dep_tree → recompute from current dep-tree.mdphase_coverage[*] → recheck per phasetbd_count → recount [TBD] markers in current architecture fileblocking_issues → remove any that are now resolvedconfidence_score → recompute all 4 dimensions + globalnext_action → update based on new statusWhat it does NOT touch:
architecture.md or architecture-patched.md contentAutoupdate output (in chat):
## Autoupdate — {datetime}
Changes detected:
drift_from_dep_tree: {N changes}
phase_coverage.phase_N: blocked → ready
tbd_count: {before} → {after}
confidence_score: {before} → {after}
{IF ready_for_specs changed to true}
✅ Architecture now ready for specs. Next: /gg-skill-specs 1
{IF still blocked}
⚠ {N} blocking issues remain — see architecture-enhancement.md
After writing the file:
[TBD] decisions that need team input (with phase-blocking impact)[RECOMMENDED] choices that deviate from the PRD's stated stackconfidence_score and whether the threshold is metconfidence_score ≥ 0.8: Next: /gg-skill-specs 1⚠ Resolve {N} TBD ADRs before /gg-skill-specs — {ADR-00X} blocks Phase {N}DO:
[BUILT] for components already in dep-tree — don't re-architect what works[RISK] in the related ADRDON'T:
# Discovery — generate architecture from PRD
/gg-skill-architecture /home/project/PRD-patched.md
# Custom output path
/gg-skill-architecture /home/project/PRD-patched.md -o /home/project/docs/architecture.md
# Harden existing architecture
/gg-skill-architecture -f /home/project/architecture.md -enh
# Auto-resolve TBDs
/gg-skill-architecture -f /home/project/architecture.md -apply
# Refresh status after dep-tree regeneration
/gg-skill-architecture -f /home/project/architecture.md -update
Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub schpill/gg-senior-tools --plugin gg-senior-tools