From dso
Use when the user wants to set up architecture rules, code standards, guardrails, fitness functions, lint configs, or enforce project conventions after onboarding has run. Reads .claude/project-understanding.md (written by /dso:onboarding) and uses Socratic dialogue to surface enforcement preferences and anti-pattern risks, then generates targeted enforcement scaffolding (CI checks, lint rules, fitness functions, ADRs) without re-running project detection. Trigger phrases include 'set up code standards', 'add architecture rules', 'enforce conventions', 'add guardrails', 'lock in patterns', 'set up linting', 'add fitness functions'.
How this skill is triggered — by the user, by Claude, or both
Slash command
/dso:architect-foundationThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
<SUB-AGENT-GUARD>
Establish positive architectural patterns and the enforcement mechanisms that keep them in place, building on the project detection already done by /dso:onboarding.
/dso:architect-foundation # interactive
/dso:architect-foundation --auto # non-interactive (see Auto-Mode Behavior below)
Supports dryrun: /dso:dryrun /dso:architect-foundation.
.claude/project-understanding.md (from /dso:onboarding).skills/shared/prompts/anti-patterns.md.skills/architect-foundation/fitness-function-templates.md.skills/shared/prompts/ci-skeleton-templates.md.PA Read understanding + detect existing artifacts
PB Socratic gap-fill (one open question at a time)
PC Recommendation synthesis (per-item accept/reject/discuss)
PD Write scaffolding (single batched confirmation)
PE Wire enforcement + ADRs + peer review
There is one approval gate per phase, not three. The Phase C per-recommendation loop replaces a blueprint-level validation loop.
When invoked with --auto:
| Phase | Behavior under --auto |
|---|---|
| PA | Same. Fail with an actionable error if project-understanding.md is missing or incomplete (list needed fields). |
| PB | Skipped — select recommended defaults from the understanding file. Report the chosen defaults in a summary table. |
| PC | Accept all synthesized recommendations without per-item review. |
| PD | Skip the "proceed with writing N files?" confirmation; skip prefill-config.sh post-write confirmation. |
| PE | Still runs /dso:review; applies critical/important findings automatically. |
Log each skipped gate as [DSO INFO] auto-mode: skipped <gate>.
.claude/project-understanding.md. Extract the facts already known (stack, interface type, test dirs, CI, any recorded architecture decisions). These must NOT be re-asked in Phase B..claude/scripts/dso onboarding/detect-enforcement-artifacts.sh. Parse JSON for arch_enforcement_md, adr_dir, adr_count, claude_md_invariants_section. If any is true, enter re-run mode (append-only merge; see "Re-run rules" below)..claude/project-understanding.md. Already known: [list 3–5 facts]. [Prior artifacts detected: …] I have N questions before generating enforcement."Ask one open-ended question at a time. No multiple-choice menus. Follow-ups are shaped by what the user says.
Question bank — ask only gaps not answered by Phase A. Each question is tagged with the AP codes it informs (see skills/shared/prompts/anti-patterns.md for definitions):
Group A — Abstraction surface (drives anti-pattern risk):
Group B — Enforcement preference:
Group C — Scope:
For each candidate enforcement mechanism, produce a recommendation citing the actual project file/pattern that triggered it. Template:
Recommendation N: <title>
AP code: <AP-x or project-specific>
Trigger: <cite file path or code pattern from the project>
Layer: <edit | test | CI>
Mechanism: <concrete — registry, frozen dataclass, typed config, grep-based boundary test, …>
Test isolation: <how tests remain isolated from the mechanism>
Fit: <why this project specifically benefits>
Present recommendations one at a time. For each: Accept / Reject / Discuss. After the full pass, confirm the consolidated accepted set, then proceed to Phase D.
Under --auto, accept all without review.
.claude/scripts/dso onboarding/plugin-inventory.sh --format table
Parse the inventory. For each accepted Phase C recommendation, check whether a plugin component already covers it. Only build custom enforcement for gaps the plugin doesn't cover. Wired hook detection is best-effort; confirm with the user if coverage is ambiguous.
.claude/scripts/dso onboarding/prefill-config.sh --project-dir "${PROJECT_DIR:-$(pwd)}"
This writes commands.test_runner, commands.lint, commands.format, commands.format_check for the detected stack, skipping keys that already have a value. Per-stack defaults and exact invocations live inside prefill-config.sh — do not duplicate them in this file. For rust-cargo, golang, convention-based, or unknown stacks the script emits empty values with a comment; prompt the user to fill them (unless --auto).
.test-index if missingif [[ ! -f .test-index ]]; then
.claude/scripts/dso generate-test-index.sh
fi
Load skills/architect-foundation/fitness-function-templates.md only when this step fires. For each accepted recommendation tagged AP-1 / AP-2 / AP-3 / AP-4 / AP-5, copy the matching template (choose stack) and customize for the project's module paths. Files land under tests/architecture/.
Also generate / update:
ARCH_ENFORCEMENT.md at repo root — one section per accepted recommendation using the Phase C template. Detected by check-onboarding.sh as evidence that scaffolding has been completed.CLAUDE.md Architectural Invariants section — one-line rules derived from the accepted recommendations.If generating CI, load skills/shared/prompts/ci-skeleton-templates.md and include only the per-stack blocks whose dependency files exist.
Present a summary: File / Type / Action (new|update) / diff-or-full-content. Ask once: "Proceed with writing all N files?" On confirmation, write all files. On partial failure, preserve already-written files and report which failed. Under --auto, skip this gate.
After files are written, verify each mechanism is actually enforced. Confirm and add as needed:
.pre-commit-config.yaml entry or a GitHub Actions step running pytest tests/architecture/ (or the stack equivalent) before merge.ruff.toml / eslint.config.js / mypy.ini.dso-config.conf key populated (not only prefilled blanks).Enforcement is inert until wired. Do not consider the scaffolding complete until this checklist is green.
For every significant architectural choice made this session, write a short ADR via:
.claude/scripts/dso onboarding/adr-upsert.sh --topic "<decision topic>" --content-file <path>
adr-upsert.sh handles deduplication: if an ADR with the same slugified topic exists, it appends a dated revision note rather than creating a duplicate file. This is the sole mechanism for ADR generation; do not hand-craft filenames.
Stage the generated files and invoke /dso:review. Apply critical/important findings.
Architect Foundation complete.
Known from project-understanding.md: [facts]
Learned via Socratic dialogue: [Q+A pairs]
Accepted recommendations (N): [titles + AP codes]
Files generated/updated: [paths]
Wiring confirmed: [CI entry, hook entries, config keys]
ADRs: [paths]
ARCH_ENFORCEMENT.md: new sections added, existing sections untouched. Skip duplicates (same recommendation title → no-op).adr-upsert.sh — no special-case logic here.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 navapbc/digital-service-orchestra --plugin dso