Implement Feat

Implement Feature — Repo-Aware ABP Code Generation

Announce at start: "I'm using the implement-feat skill. I'll scan your repo first, reconcile the Feat Spec against what already exists (REUSE / UPDATE / CREATE), gate on your approval, plan the artifacts with quality pre-flight, gate again, cut a feat/<slug> branch from develop, then synthesize. Migrations and commits stay manual."

Approval gates (both absolute):

• No source file is written or edited before the user explicitly approves the Reconciliation Plan (Phase 3 gate) AND the Artifact Plan (Phase 5 gate).
• Both gates use AskUserQuestion. Never ask as prose.

FS lock check:

• Refuse a Feat Spec containing [TODO], [PENDING], [TBD], or [PLACEHOLDER].
• Refuse a Feat Spec whose Open Blockers section lists a Conflict at severity critical or high.

Reconciliation discipline:

• Every FS element carries exactly one of REUSE_AS_IS / UPDATE_IN_PLACE / CREATE_NEW / CONFLICT.
• Every Command carries exactly one realization type drawn from {AppService, BackgroundJob, IHostedService, HubMethod, EventHandler, CliCommand}. Ambiguous → AskUserQuestion.
• Existing DTO / Entity / Validator / Mapper / Permission constant / AppService method that already satisfies the FS is reused, not re-synthesized.

Synthesis discipline:

• REUSE_AS_IS files are never opened.
• UPDATE_IN_PLACE files are edited via str_replace with a unique anchor — never full-file rewrite.
• CREATE_NEW paths must not exist on disk at synthesis time. Drift between plan and synth halts with FILE_DRIFT.
• No file is overwritten without an explicit UPDATE_IN_PLACE decision.

Branch discipline:

• Synthesis runs on a feature branch, never on develop / main / master. Default branch name: feat/<feature-slug> from develop. Both are overridable via AskUserQuestion and via CLAUDE.md (branch_naming_pattern, default_base_branch).
• Working tree must be clean before the branch is cut — dirty tree halts with WORKING_TREE_DIRTY.
• Source branch must exist locally — missing branch halts with BASE_BRANCH_MISSING.
• The skill never runs git commit, git push, git pull, git fetch, git merge, git rebase, or any rewrite of history. It creates the branch, checks it out, and writes files. Commits remain the user's manual step.

Architecture:

• No Controller / ControllerBase / [ApiController] classes. AppService methods + [RemoteService] + [Authorize] are the HTTP entry point.
• No domain events published from the Domain layer. Cross-aggregate orchestration goes through a DomainService; deliberate cross-module reactions go through an EventHandler in Application.
• No ILocalEventBus.PublishAsync for cross-aggregate writes.
• No user-visible strings inlined — IStringLocalizer<<Feature>Resource> keys only.
• No dotnet ef migrations add or dotnet ef database update. Migrations are the user's manual step.
• No git commit, git push, git pull, git fetch, git merge, or git rebase. Commits are the user's manual step.

Quality gates (1–10): see references/code-quality.md. Gate 1 (no controllers) is an abort condition; gates 2–10 halt synthesis pending user revision or explicit override.

Overview

This skill differs from a naive code generator in three ways:

1. It scans the repo first. repo-scout enumerates every project and indexes candidates by name, shape, and signature — DTOs, entities, AppServices, validators, mappers, permission constants, background workers, hosted services, hubs, event handlers, CLI commands.

2. It reconciles the FS against what already exists. reconciler does a three-way comparison (FS element ↔ existing candidate ↔ skill's target pattern) and classifies every FS element. The user approves the result before any planning begins.

3. Commands are pluggable in their execution model. Each Command's realization is read from the FS page's **Execution model:** field plus repo evidence. Not every Command is an AppService method.

Outcomes: bidirectional traceability, manual migrations, two strict approval gates, ten quality gates, no controllers ever generated.

The 8 phases

Cohorts inside Phase 6, serial: A (Domain.Shared) → B (Domain) → C (Application.Contracts) → D (Application + EFCore + auxiliary projects).

Phase detail

Phase 0 — Scope + CLAUDE.md

1. Read feature slug from arguments. Absent → AskUserQuestion listing slugs found under <wiki_local_path>/feat-specs/.
2. Verify CLAUDE.md is readable. Extract fields per the CLAUDE.md fields table below. Missing required field → halt. Missing recommended → soft warning. Missing optional → use default.
3. AskUserQuestion to confirm scope and proceed.

Phase 1 — FS load ‖ repo scan

Dispatch fs-loader and repo-scout simultaneously (independent inputs).

• fs-loader reads the Feat Spec + every linked DDD node page; produces FS catalog. Halts on placeholder tokens, blocking conflicts, broken links.
• repo-scout enumerates projects, indexes candidate artifacts by kind + shape fingerprint, and validates ABP scaffolding (6 projects, 5 module classes, DbContext applies configs). Halts on missing scaffolding.

See agents/fs-loader.md, agents/repo-scout.md.

Phase 2 — Reconciliation

reconciler consumes both catalogs.

1. Realization assignment per Command:
   • FS page declares **Execution model:** → use it.
   • Else infer: Scheduled*/Nightly*/Recurring* → BackgroundJob; *Handler/Handle*/On*Async → EventHandler; Broadcast*/Notify*/Push* → HubMethod; long-running watchers → HostedService; user-invoked verbs → AppService.
   • Ambiguous → AskUserQuestion per Command.
2. Three-way classification per FS element: REUSE_AS_IS / UPDATE_IN_PLACE / CREATE_NEW / CONFLICT.
3. Realization feasibility: required infrastructure missing (e.g., BackgroundJob but no worker project) → CONFLICT for the user to resolve.

See agents/reconciler.md. See references/command-realizations.md for realization detection. See references/update-in-place.md for edit anchor rules.

Phase 3 — Reconciliation gate

Present plan grouped by decision (REUSE / UPDATE / CREATE / CONFLICT) with rationale per row. AskUserQuestion: approve / revise / cancel. revise collects feedback and reruns reconciler with overrides. CONFLICT-containing plan never proceeds without a user-chosen resolution.

Phase 4 — Planning + traceability + quality pre-flight

planner runs per layer in parallel (Domain, Domain.Shared, Application.Contracts, Application, EFCore, plus auxiliary cohorts for Worker / Hubs / EventHandlers / Cli when those realizations have decisions). Each emits descriptors: create, update_edit, or reuse_reference_only.

After per-layer planning, the planner runs holistic checks on the merged manifest (one synchronous step, not a separate agent):

• Forward coverage: every FS element has at least one descriptor.
• Backward provenance: every descriptor has at least one FS source.
• Reconciliation coherence: descriptor action matches reconciliation decision.
• Pair integrity: Permissions constants update ↔ Permission provider update; new entity ↔ EF configuration; new AppService ↔ DI registration.
• Cohort dependency: no back-edge from later cohort to earlier.
• Anchor uniqueness: every update_edit anchor is unique in its target file.
• Quality pre-flight (gates 1–10): would the planned content violate any quality gate? Surface findings.

Failure halts; main agent re-dispatches the planner with defect list (cap 2 replans).

See agents/planner.md. See references/code-quality.md.

Phase 5 — Artifact plan gate

Preview includes: new files (path + summary + FS source), unified diffs per update_edit, reuse references, traceability matrix, quality pre-flight result, CLAUDE.md defaults used, manual migration commands.

AskUserQuestion: approve / revise / cancel.

Phase 6 — Branch setup + Synthesis

6a. Branch setup (main agent, before any file write):

1. Run git status --porcelain. Non-empty → halt WORKING_TREE_DIRTY. The user must commit or stash before re-running.
2. Compute the proposed branch name from branch_naming_pattern (default feat/<feature-slug>) and the proposed base from default_base_branch (default develop).
3. Verify the base branch exists locally: git rev-parse --verify <base>. Missing → halt BASE_BRANCH_MISSING with hint to git fetch it manually (network is forbidden inside the skill).
4. Check whether the proposed branch already exists locally: git rev-parse --verify <branch>. If it exists → AskUserQuestion: checkout existing / pick a different name / cancel.
5. AskUserQuestion to confirm: use feat/<slug> from develop / customize branch or base / stay on current branch (advanced) / cancel.
   • use ... → git checkout <base> && git checkout -b <branch>.
   • customize ... → collect new branch name and base via follow-up AskUserQuestion, then create.
   • stay on current branch → log the chosen ref; flag in the final report as branch_setup: skipped. Only available when the current ref is not develop / main / master.
   • cancel → exit USER_CANCELLED, no I/O.
6. Record the branch name, base branch, and base commit SHA for the final report.

No commits are made by the skill. After build is green (Phase 7) the user reviews and commits manually.

6b. Synthesis:

synthesizer runs cohort A → B → C → D serially; files within a cohort run in parallel.

Per descriptor:

• create → render template, write file. Refuse if path exists (PHANTOM_CREATION).
• update_edit → load file, verify content hash matches plan-time hash (FILE_DRIFT halt on mismatch), apply each str_replace with anchor uniqueness check.
• reuse_reference_only → no I/O.

After each file is written, synthesizer scans it against the 10 quality gates. Gate 1 (controller detected) → abort the entire phase. Gates 2–10 → halt with violation report; main agent re-asks user (revise / override / cancel).

See agents/synthesizer.md. References per kind:

• Domain: references/domain-layer.md, references/domain-services.md, references/abp-base-classes.md, references/abp-built-in-entities.md
• Domain.Shared: references/domain-shared-layer.md, references/localization.md
• Application.Contracts: references/dtos-validators.md, references/permissions.md
• Application: references/appservices.md, references/mapperly.md
• EFCore: references/ef-core.md
• Auxiliary realizations: references/command-realizations.md
• Update edits: references/update-in-place.md
• All synthesis: references/code-quality.md

Phase 7 — Build + repair

build-validator runs dotnet build. On failure:

• Errors all in files synth wrote AND iteration < 3 → main agent dispatches synthesizer in repair mode with {file_path, current_content, compile_errors}. Repeat from Phase 7.
• Any error in a file synth did not write → halt (cross-cutting).
• Linker / NuGet error → halt.
• Iteration ≥ 3 → halt REPAIR_CAP_REACHED.

See agents/build-validator.md.

Phase 8 — Final report

Main agent writes <wiki_local_path>/feat-specs/<feature-slug>/IMPLEMENTATION_REPORT_<Feature>.md from the template. Sections: metadata, reconciliation summary (counts), inventory per decision, traceability matrix, build status, quality coverage (per-gate from synthesizer's scan results), manual next steps (migrations, permission seeding, tests).

See templates/implementation-report-template.md.

Sub-agents

fs-loader and repo-scout run concurrently in Phase 1. Within Phase 4, planner workers run in parallel per layer. Within Phase 6, synthesizer workers run in parallel per file inside a cohort but cohorts execute serially.

Tool permissions

Forbidden everywhere: dotnet ef *, dotnet run, dotnet test, dotnet add, dotnet publish, network, wiki write, GitLab write, full-file overwrite of non-empty existing files, git commit, git push, git pull, git fetch, git merge, git rebase, git reset --hard, git stash, any history-rewriting git command.

CLAUDE.md fields

Missing required → halt at Phase 0. Missing optional → one-line soft warning listing the default used.

When NOT to use

• No Feat Spec on disk for the feature slug.
• Feat Spec contains placeholder tokens.
• Feat Spec has unresolved critical/high Conflicts.
• CLAUDE.md absent or missing required fields.
• No .sln file under src_path.

Outcomes

Expected output

• Two approved gates (reconciliation + artifact plan).
• A fresh feat/<feature-slug> branch (or user-customized name) checked out from develop, holding all synthesized changes.
• New C# files + in-place edits realizing the feature.
• All synthesized code passes the 10 quality gates.
• dotnet build green.
• IMPLEMENTATION_REPORT_<Feature>.md with full REUSE / UPDATE / CREATE inventory + quality coverage + branch metadata (name, base, base SHA).
• 100% bidirectional traceability.
• No migrations run. No commits made.

Next step

After completion: review the quality coverage report, run the migration commands the report lists, seed permission grants, write tests, then git add / git commit / git push the feature branch and open the MR. Then return to generate-feat-spec for the next milestone.