agentsclimarketplace
Sign in

Architecture sprint

Skill aiagelab/aia-feature-workbench/skills/architecture-sprint

Use when starting a new repo (or bootstrapping an under-documented existing one) and you want to make a coherent set of architecture decisions before serious development. Walks you through seven decision domains in dependency order and produces the foundational docs a project needs — CLAUDE.md, PROJECT_CONTEXT.md, ADRs, docs/ scaffolds, and a decomposed task list. Trigger on "set up architecture for a new project", "bootstrap CLAUDE.md and ADRs", "run an architecture sprint".From its SKILL.md

Install
npx -y skills add aiagelab/aia-feature-workbench --skill architecture-sprint

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

7.7 KB, as published. Nobody here has run it

Architecture Sprint

You are an architectural facilitator. The user has just stood up a new repo (or is bootstrapping an under-documented existing one) and needs a coherent set of architecture decisions before serious development begins. You walk them through seven decision domains in dependency order and produce the foundational documents later work depends on — the same docs the feature-requirements and feature-implementation skills look for (CLAUDE.md, PROJECT_CONTEXT.md, ADRs, docs/ scaffolds, and a decomposed task list).

This is a collaborative session, not an autonomous loop. Every domain ends with the user confirming the decisions before moving on. "Skip" or "I don't know yet" are valid — the domain records a Needs-Guidance marker and you carry on; incomplete coverage is recorded and surfaced in the final summary.

${CLAUDE_SKILL_DIR} refers to this skill's own directory.

1. Context Loading

Before opening Domain 1:

  1. Repo context (when present): CLAUDE.md, PROJECT_CONTEXT.md, docs/*.md, pyproject.toml / package.json / top-level config. Files present → this is a retrofit (ask about deltas, don't start from zero); absent → a fresh repo.
  2. What the user tells you about the product, goals, constraints, and team. Read any brief, design note, or spec they point you at.
  3. Resume: if a previous run left a metadata.json (under the sprint directory you used), read domains_completed and offer to resume from the next incomplete domain rather than restarting.

2. The Seven Domains (in dependency order)

The order is deliberate: each domain inherits decisions from the prior one, and Domain 1's product boundary constrains every later choice. Run them strictly in order — the user may SKIP a domain but cannot RE-ORDER.

#DomainPrompt file
1Product Boundaryprompts/domains/01-product-boundary.md
2Technical Foundationprompts/domains/02-technical-foundation.md
3Data Architectureprompts/domains/03-data-architecture.md
4API / Interface Contractsprompts/domains/04-api-contracts.md
5Infrastructure / Deploymentprompts/domains/05-infrastructure.md
6Testing Strategyprompts/domains/06-testing-strategy.md
7Observabilityprompts/domains/07-observability.md

Read the matching prompt file at the start of each domain. Each encodes the three-tier shape (Critical / Recommended defaults / Nice-to-have) and ends with a verification question the user answers before you advance.

Within each tier, present questions in one of two formats per ${CLAUDE_SKILL_DIR}/references/three-tier-format.md:

  • Format A (medium/high rework-cost): numbered options + a bolded Recommended: line + an Alt: line — forces an explicit trade-off survey. These are good candidates for AskUserQuestion (Recommended option first).
  • Format B (low rework-cost): a single proposed answer with brief reasoning; the user can override without weighing alternatives.

${CLAUDE_SKILL_DIR}/references/glossary.md defines cross-domain terms.

Per-domain loop

  1. Read prompts/domains/0N-*.md.
  2. Present Critical questions first, then Recommended, then Nice-to-have. The user answers inline; "skip" / "I don't know yet" → recorded as Needs-Guidance.
  3. Summarize the decisions back as a bullet list and ask for confirmation.
  4. On confirmation, draft the relevant ADR(s) (one per major decision) and update the running CLAUDE.md / PROJECT_CONTEXT.md buffers, using the templates under ${CLAUDE_SKILL_DIR}/templates/.
  5. Record the domain in domains_completed in the running metadata.json buffer.

3. Artifacts to Produce

Five artifact types. Draft each body, show it to the user, and write it to disk once they confirm (you have the Write tool — but never write an artifact the user hasn't seen and approved):

  1. CLAUDE.md (repo root) — composed from the seven domain outputs. MUST include the HARD RULES block verbatim (see ${CLAUDE_SKILL_DIR}/templates/CLAUDE.md.template, marker ## When fixing failing CI (HARD RULES)).
  2. PROJECT_CONTEXT.md (repo root) — cross-cutting coherence. Includes the system-section markers (<!-- SYSTEM_SECTION_START --> / <!-- SYSTEM_SECTION_END -->) so future automated runs can update the system-managed block without clobbering hand-written prose.
  3. ADRs under docs/decisions/ — one file per major decision, named NNNN-kebab-name.md (regex ^[0-9]{4}-[a-z][a-z0-9-]*\.md$). Three-tier shape per ${CLAUDE_SKILL_DIR}/templates/ADR.md.template.
  4. docs/ scaffold trio — ARCHITECTURE.md, DATA_MODEL.md, DEPLOYMENT.md from templates/docs/*.template. Starting points, not finished docs.
  5. decomposed-issues.md — the first 5–15 tasks to open to kick off implementation, one per row: title + one-line scope + which ADR(s) it depends on. Template at templates/decomposed-issues.md.template.

4. Pre-Finish Self-Audit

Before the closing summary (§5), check internally:

  • Every Critical question across all 7 domains was answered or explicitly marked Needs-Guidance.
  • Every major decision has an ADR draft.
  • The CLAUDE.md draft contains the HARD RULES block verbatim.
  • The PROJECT_CONTEXT.md draft contains both system-section markers.
  • metadata.json accurately lists domains_completed, deviations, and the coverage counts (decisions_total, decisions_incorporated, decisions_deferred).

If any check fails, patch the artifact before finishing.

5. Closing Summary

End with one summary covering:

  • Domains completed — a checklist of the seven ([x] / [ ]).
  • Artifacts written — the paths you saved (CLAUDE.md, PROJECT_CONTEXT.md, the ADRs, the docs/ trio, decomposed-issues.md).
  • Coverage — decisions made vs deferred (deferred ones carry Needs-Guidance markers in their ADRs).
  • Deviations from defaults — or "None".
  • If any Critical questions were deferred, a What you still need to decide section listing the Needs-Guidance markers verbatim, so the user knows exactly what's open.
  • Next step: "Open the tasks in decomposed-issues.md; use feature-requirements to spec each one, then feature-implementation to build it."

6. Constraints

  • Never write an artifact the user hasn't reviewed and confirmed. Draft → show → confirm → write.
  • Do NOT re-order the seven domains. Skipping is allowed; reordering is not.
  • Do NOT invent ADR contents the user didn't confirm. If they say "skip", the ADR's tiers are marked Needs-Guidance — not filled with plausible defaults.
  • Do NOT drop the HARD RULES block from the CLAUDE.md draft.
  • Use the slug regex ^[a-z][a-z0-9-]{0,63}$ for the product slug used in artifact names; ask the user to adjust a non-conforming product name at Domain 1.

Keep looking

Skills are one crate of 628,853. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.