SDD Brownfield Adoption (/sdd-adopt)

Dùng để adopt SDD+ADD vào repository có source hoặc tạo Reverse Spec cho module legacy. Đây là default khi repository đã có source hoặc đã có canonical shared-context governance. Trên repository đã adopt template, /sdd-template-update là canonical route cho template drift; /sdd-adopt không reset canonical header hay approved profile đã tồn tại.

Parameters

• --stack=<tech-stack>: Optional explicit stack.
• --reverse-feature=<feature-slug>: Optional.
• --path=<module-path>: Optional; used with --reverse-feature.
• --project-ownership=solo|team: Optional Human governance setting; default team.
• --agent-execution=direct|orchestrated: Optional execution setting; default direct. Use orchestrated only when the runtime worker capability is observed.
• --team-size=solo|team: Deprecated composite alias for one transition release: solo maps to solo/direct; team maps to team/orchestrated. Emit a migration warning.

solo is one Human project owner and may use orchestrated workers. team is multiple Human collaborators and may use direct execution. Do not infer either from the other. Reject --team-size when combined with --project-ownership or --agent-execution; when canonical shared-context headers already exist, reject --team-size because the alias is valid only while both headers are absent. Canonical flags select only their own axis.

Adoption workflow

1. Survey root, manifest, lockfile, runtime/bootstrap, database/migration, CI, test configuration, source layout and docs.
2. Create/update Architecture Profile with evidence, confidence and conflicts for runtime, framework, DB, ORM/query, validation and test/build/lint commands.
3. Resolve approved profile → clear repository evidence → explicit --stack → core-only baseline.
4. Keep conflicts PENDING HUMAN REVIEW; do not self-resolve.
5. Context/Spec may be business-neutral; Plan/Tasks/execution need selected/evidenced binding and exact command.
6. Generate/reconcile governance from actual repository; never overwrite approved Constitution rules.
7. Install template-owned docs and support scripts under their staged/NEVER safety rules.

Governance generation

Generate AGENTS.md, CLAUDE.md, .agentignore and .gitignore from observed convention, paths, commands and secret boundaries. Persist Project Ownership and Agent Execution independently in shared context. If a legacy collaboration header is found and new headers are absent, create a durable PENDING HUMAN REVIEW migration recommendation; never rewrite it silently.

/add-execute maps persisted orchestrated execution to Claude Code Agent only with observed host evidence; unavailable runtime is BLOCKED, not direct fallback. Adoption does not copy assumed settings, identity provider or permission configuration. A solo Human owner may persist review; a team review must be persisted by an authorized Human collaborator. Agents never self-approve or push.

Reverse Spec

With --reverse-feature and --path:

1. Observe source and tests; produce Context, Spec, Plan and Tasks as evidence of current behavior.
2. Keep Spec DRAFT; existing code is not approved business intent.
3. Include Intent Packet, Methodology Profile, Feature Lock/deferred-work decision, state-change classification and trace/sync implications.
4. Add @ears or change source only after explicit scope approval and relevant profile gate.

Shared contract and execution

Only the named contract owner changes frozen shared contracts. Direct execution retains the same ownership/checkpoint constraints. Orchestrated execution requires task ID, frozen version, ownership boundary, selected binding/evidence, exact commands, checkpoint and audit reference in every worker packet.

AI Recommendation and Human Final Review

Create .sdd/reviews/adopt-<slug>.md with canonical protocol block. Include discovered evidence, unresolved/conflicting binding, governance impact, selected ownership/execution settings, migration impact, recommendation and required Human decision. Agent does not self-approve or treat reverse-engineered behavior as approved business intent.

Hướng dẫn sử dụng

• Khi dùng: Bootstrap governance in an existing repository or reverse-spec a named legacy module without treating behavior as approved intent.
• Không dùng: Không dùng để overwrite approved Constitution, silently rewrite existing canonical governance, or execute feature code.
• Input: Optional explicit --stack, --reverse-feature with --path, and canonical ownership/execution flags; reject --team-size when canonical headers exist or with canonical flags.
• Điều kiện trước: Repository root and evidence are readable; existing canonical shared-context headers take precedence and are preserved.
• Evidence: Adoption survey, Architecture Profile conflicts, generated/reconciled governance, reverse Spec DRAFT, and .sdd/reviews/adopt-<slug>.md.
• Dừng khi: Evidence conflicts, missing binding for planning, unsafe overwrite boundary, or reverse path/feature is invalid.
• Human quyết định: Human approves adoption scope, migration, bindings and reverse-spec intent; Agent never self-approves or pushes.
• Lệnh tiếp theo: After persisted adoption review, use its exact Follow-up; normally /sdd-context --feature=<feature-slug> for new feature work.
• Ví dụ: /sdd-adopt --reverse-feature=legacy-orders --path=src/orders records current behavior as DRAFT only.

Completion output

Use the Completion output contract. Summarize observed repository evidence, generated/reconciled governance, profile conflicts and reverse-spec state when applicable. Adoption review is Human decision required; an authorized Human reviewer records the selected non-placeholder decision, reviewer identity and persisted Follow-up with /sdd-review --target=.sdd/reviews/adopt-<slug>.md --status=<APPROVED|REVISE|REJECTED> --decision="<human decision>" --reviewer="<authorized human reviewer>" --follow-up="<exact next command or required action>". Only the persisted Follow-up can select a next feature command. Conflicting/missing binding evidence is BLOCKED; do not infer a stack or treat reverse-engineered behavior as approved intent.