Description
Make AGENTS.md the canonical instruction source throughout the repository and ensure the generated skill-sync tooling cannot restore the retired inverse symlink. Remove harness-specific model contradictions from the portable project contract and give cloned-repo agents direct blueprint/deployment entrypoints.
Acceptance Criteria
- #1 scripts/sync-skills.sh –check passes while requiring root AGENTS.md to be a regular canonical file and root CLAUDE.md to import it
- #2 Running make skills-sync cannot delete or replace the canonical root AGENTS.md
- #3 dashboards/AGENTS.md contains the local canonical rules and dashboards/CLAUDE.md imports it without duplicating root guidance
- #4 AGENTS.md routes fan-out by canonical roles instead of hard-coding another harness model, and its branching wording matches effective repository policy
- #5 AGENTS.md points agents to create-blueprint, initial-setup, and verify-deployment; SIGNALS.md and ARCHITECTURE.md identify AGENTS.md as canonical
- #6 codex/ scratch artifacts are ignored in a fresh clone
Definition of Done
- #1 make gate (build vet test race rw-proto-check spdx-check forbidden-words)
- #2 make blueprint-schema (only if a blueprint field or construct/workload config struct changed)
- #3 DRY_RUN=true go run ./cmd/synthkit -once -dump — inventory diffed against signals/
Implementation Plan
- Preserve the observed red make skills-check failure as the bug proof, then rewrite sync/check behavior around AGENTS.md canonical plus CLAUDE.md import.
- Create the dashboards local AGENTS/CLAUDE pair and remove harness-specific model/branch contradictions from root instructions while preserving role-based fan-out.
- Add operational skill entrypoints and correct adjacent canonical references.
- Land codex/ ignore and verify skills-check plus instruction/import invariants.
Implementation Notes
Wave 1 started. File owner: instruction lane owns .gitignore, root/dashboard instruction files, scripts/sync-skills.sh, Makefile, SIGNALS.md, ARCHITECTURE.md, and docs/cli.md. It must not touch README or plugin skill files.
Implementation complete pending integrated review/gate. The sync command now manages only .claude/skills and .agents/skills, rejects invalid AGENTS/CLAUDE pairs, and cannot replace canonical AGENTS.md. Root and dashboards CLAUDE.md files import nearest canonical AGENTS.md files; portable fan-out and direct-main policy wording plus operational skill entrypoints are aligned. Focused evidence: red make skills-check reproduced the inverse-symlink defect; make skills-check, make skills-sync, bash -n scripts/sync-skills.sh, instruction-pair inspection, and git diff –check then passed. Full gate remains root-owned.
Integrated evidence: CodeRabbit review 4 completed with zero findings after fixes; make gate passed all build, vet, helper, Go test, race, RW2 provenance, SPDX, and forbidden-words legs. The 3,151-line dry-run inventory completed for all 26 blueprints with no hard error lines; this task changed no signal contract.
Final Summary
Landed in 9c93f5c: AGENTS.md is canonical at root and dashboards scope, CLAUDE.md files are import adapters, skill sync cannot replace instructions, fan-out is role-based, and clone-local operational entrypoints are explicit. Verified by make skills-check/sync, SHA-preservation proof, clean CodeRabbit review 4, make gate, and dry-run inventory.