create-agdf 0.1.0 → 0.1.2

package/README.md

@@ -6,7 +6,6 @@ Bootstrap AGDF for one repository.
 
 ```bash
 npm create agdf@latest copilot
-npm create agdf@latest claude
 npm create agdf@latest both
 ```
 
@@ -15,11 +14,26 @@ Optional flags:
 - `--dir <path>` write into a specific directory
 - `--force` overwrite existing generated files
 
-## Targets
+## Targets and existing AGENTS.md
 
-- `copilot` writes `AGENTS.md` and `.github/copilot-instructions.md`
-- `claude` writes `AGENTS.md` and prints the Claude plugin installation step
-- `both` writes both instruction files and prints both next steps
+- `copilot` writes `AGENTS.md` and visible repository skills under `.github/skills/`
+- `both` writes the same Copilot-facing files and reminds you to install the Claude plugin separately
+
+If the target repository already has an `AGENTS.md`, `create-agdf` preserves it and writes `AGENTS.agdf.md` instead of replacing your existing instructions. Merge the AGDF fragment into your current `AGENTS.md` when you want Copilot to load both instruction sets. Use `--force` only when you explicitly want to overwrite generated files.
+
+## Single source of truth
+
+The repository-facing AGDF sources are maintained in:
+
+- `AGENTS.md`
+- `plugin/skills/`
+- `plugin/meta/agdf-runtime-contract.md`
+
+The published package assets are generated from these repository sources only at pack/publish time. The package does not keep a second manually maintained template tree.
+
+```bash
+npm run sync-package-assets
+```
 
 ## Publishing
 

package/bin/create-agdf.js

@@ -7,16 +7,28 @@ import process from "node:process";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = resolve(__dirname, "..");
-const templatesRoot = join(packageRoot, "templates");
+const generatedRoot = join(packageRoot, "generated");
 const pluginInstallCommand = "claude plugin add arndtgold/ai-native-governance-delivery-framework";
-const allowedTargets = new Set(["copilot", "claude", "both"]);
+const allowedTargets = new Set(["copilot", "both"]);
+const agdfFragmentPath = "AGENTS.agdf.md";
+const copilotSkillFiles = [
+  join(".github", "skills", "README.md"),
+  join(".github", "skills", "agdf-runtime-contract.md"),
+  join(".github", "skills", "agdf-gate-check", "SKILL.md"),
+  join(".github", "skills", "agdf-brownfield-analysis", "SKILL.md"),
+  join(".github", "skills", "agdf-task-plan-review", "SKILL.md"),
+  join(".github", "skills", "agdf-clean-implementation-review", "SKILL.md"),
+  join(".github", "skills", "agdf-code-review", "SKILL.md"),
+  join(".github", "skills", "agdf-qa-gate", "SKILL.md"),
+  join(".github", "skills", "agdf-release-or", "SKILL.md"),
+  join(".github", "skills", "agdf-delivery-closeout", "SKILL.md"),
+];
 
 function printUsage() {
   console.log(`create-agdf
 
 Usage:
   npm create agdf@latest copilot
-  npm create agdf@latest claude
   npm create agdf@latest both
 
 Options:
@@ -78,7 +90,7 @@ function parseArgs(argv) {
   }
 
   if (!target || !allowedTargets.has(target)) {
-    console.error("Please choose one target: copilot, claude, or both.");
+    console.error("Please choose one target: copilot or both.");
     printUsage();
     process.exit(1);
   }
@@ -90,8 +102,8 @@ function parseArgs(argv) {
   };
 }
 
-function loadTemplate(relativePath) {
-  return readFileSync(join(templatesRoot, relativePath), "utf8");
+function loadAsset(relativePath) {
+  return readFileSync(join(generatedRoot, relativePath), "utf8");
 }
 
 function writeGeneratedFile(targetDir, relativePath, content, force) {
@@ -105,25 +117,28 @@ function writeGeneratedFile(targetDir, relativePath, content, force) {
   writeFileSync(outputPath, content, "utf8");
 }
 
-function generatedFilesForTarget(target) {
+function generatedFilesForTarget(target, targetDir, force) {
+  const agentsTargetPath = existsSync(join(targetDir, "AGENTS.md")) && !force ? agdfFragmentPath : "AGENTS.md";
   const files = [
     {
-      path: "AGENTS.md",
-      content: loadTemplate("AGENTS.md"),
+      path: agentsTargetPath,
+      content: loadAsset("AGENTS.md"),
     },
   ];
 
   if (target === "copilot" || target === "both") {
-    files.push({
-      path: join(".github", "copilot-instructions.md"),
-      content: loadTemplate(join(".github", "copilot-instructions.md")),
-    });
+    for (const skillPath of copilotSkillFiles) {
+      files.push({
+        path: skillPath,
+        content: loadAsset(skillPath),
+      });
+    }
   }
 
   return files;
 }
 
-function printNextSteps(target, destination, files) {
+function printNextSteps(target, destination, files, wroteAgentsFragment) {
   console.log("");
   console.log(`AGDF bootstrap complete in ${destination}`);
   console.log("");
@@ -134,18 +149,22 @@ function printNextSteps(target, destination, files) {
 
   console.log("");
   console.log("Next steps:");
-  if (target === "claude" || target === "both") {
+  if (wroteAgentsFragment) {
+    console.log(`- Existing AGENTS.md detected. Merge ${agdfFragmentPath} into your current AGENTS.md before using Copilot with AGDF.`);
+  }
+  if (target === "both") {
     console.log(`- Install the Claude Code plugin: ${pluginInstallCommand}`);
   }
   if (target === "copilot" || target === "both") {
-    console.log("- In GitHub Copilot CLI, run /instructions to confirm that the repository instructions are loaded.");
+    console.log("- In GitHub Copilot CLI, run /instructions after the AGENTS.md step is complete to confirm that AGDF instructions and the repository skills are visible.");
   }
   console.log("- Commit the generated files so the repository becomes the source of truth.");
 }
 
 function main() {
   const options = parseArgs(process.argv.slice(2));
-  const files = generatedFilesForTarget(options.target);
+  const files = generatedFilesForTarget(options.target, options.dir, options.force);
+  const wroteAgentsFragment = files.some(file => file.path === agdfFragmentPath);
 
   try {
     for (const file of files) {
@@ -156,7 +175,7 @@ function main() {
     process.exit(1);
   }
 
-  printNextSteps(options.target, options.dir, files);
+  printNextSteps(options.target, options.dir, files, wroteAgentsFragment);
 }
 
 main();

package/generated/.github/skills/README.md

@@ -0,0 +1,18 @@
+# AGDF repository skills
+
+These repository skills were generated from the AGDF source repository and are intended to be checked into this repository.
+
+## Skills
+
+- `agdf-brownfield-analysis`
+- `agdf-clean-implementation-review`
+- `agdf-code-review`
+- `agdf-delivery-closeout`
+- `agdf-gate-check`
+- `agdf-qa-gate`
+- `agdf-release-or`
+- `agdf-task-plan-review`
+
+## Runtime contract
+
+Shared output and gate rules for this checkout live in `agdf-runtime-contract.md`.

package/generated/.github/skills/agdf-brownfield-analysis/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: agdf-brownfield-analysis
+description: Use this skill before implementation in an existing codebase, especially for feature extensions, bug fixes, refactorings, or changes to existing modules. It analyzes existing artefacts, current coverage, reuse strategy, risks, and the minimal clean implementation path. Use it before CD+Tests.
+---
+
+# brownfield-analysis
+
+## Purpose
+Ensure implementation in an existing system is Brownfield-oriented, not Greenfield-style.
+
+The skill answers:
+
+- which existing artefacts matter
+- what already exists fully or partially
+- what can be reused, extended, or refactored
+- whether new artefacts are really needed
+- architecture, compatibility, migration, and regression impact
+- the minimal clean implementation path
+- whether Context Graph impact exists without automatically creating a node
+
+## Runtime Contract
+Use `../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
+
+Brownfield-specific output must make evidence, missing existing-system view, parallel-structure risk, reuse strategy, and the minimal next step visible.
+
+## Rules
+1. Brownfield first: understand the existing codebase before implementation.
+2. Reuse-before-create: prefer existing modules, services, components, tables, endpoints, tests, and configuration.
+3. Minimal clean slice: choose the smallest durable intervention, not merely the smallest technical diff.
+4. No silent parallel structures.
+5. Existing architecture, naming, error handling, logging, security, and test conventions are binding unless deviation is justified.
+6. What is not visibly evidenced does not count as existing.
+7. Async execute paths must not become a second product-policy decision point.
+8. Visible state ownership must be checked for chat, rendering, scrolling, recovery, and status problems.
+9. SoT/runtime/product-semantics drift must be named; if official behaviour must be decided first, recommend UR or equivalent product direction.
+10. Large UI surfaces and state hooks must be checked for mixed render, view-model, derived state, orchestration, persistence, and recovery ownership.
+11. Context Graph impact must be curated; it is not a review log or version index.
+12. Specification archive migrations must follow the archive index if present.
+
+## When To Use
+- before `CD+Tests`
+- before changes to an existing repository
+- bug fixes in existing modules
+- feature extensions in existing architecture
+- refactorings
+- unclear existing coverage
+- risk of new parallel structures
+- a TP is clear but its connection to the existing system is not
+
+## Inputs
+Use what is available:
+
+- Task Plan, `task_id`, `story_id`
+- project structure
+- affected files, modules, services, APIs, data models
+- existing tests
+- architecture notes from PRD or SD
+- repository conventions
+
+If inputs are missing, work only from observable evidence and mark gaps explicitly.
+
+## Workflow
+1. Identify affected tasks and scope.
+2. Find relevant existing artefacts.
+3. Assess current coverage before new implementation:
+   - `fully_done`
+   - `partially_done`
+   - `not_done`
+4. Choose reuse strategy:
+   - `extend`
+   - `refactor`
+   - `replace`
+   - `new`
+5. Assess change impact:
+   - files/modules
+   - interfaces
+   - data model/migrations
+   - backwards compatibility
+   - regression tests
+   - side effects
+6. Check parallel-structure risk.
+7. Check SoT/runtime/product-semantics drift.
+8. Check primary visible ownership for UI/status/recovery paths.
+9. Check UI monolith risk for large surfaces or central hooks.
+10. Check Context Graph impact according to `../agdf-runtime-contract.md`.
+11. Recommend the minimal clean implementation path.
+
+## Output
+Use a concise structure:
+
+```text
+## Brownfield Analysis
+- decision: pass | revise | block | not_applicable
+- scope:
+- evidence:
+- missing_evidence:
+- current_coverage:
+- reuse_strategy:
+- risks:
+- context_graph_impact:
+- required_next_step:
+```
+
+## Pass / Revise / Block Guidance
+- `pass`: existing owners are understood, reuse path is clear, and no blocking drift or parallel structure risk remains.
+- `revise`: relevant evidence, tests, ownership, or reuse path is incomplete.
+- `block`: implementation would create a second SoT, second owner, unresolved product semantics, or hard unmitigated risk.
+
+## Forbidden
+This skill must not:
+
+- propose a Greenfield replacement without evidence
+- silently accept overlapping ownership
+- convert product-semantics drift into a mere refactor
+- create Context Graph nodes automatically
+- treat archive links as active current specification signals

package/generated/.github/skills/agdf-clean-implementation-review/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: agdf-clean-implementation-review
+description: Use this skill to determine whether an implementation is a clean primary solution or whether fallbacks, workarounds, guards, defaults, shims, or parallel structures have made it unnecessarily complex. Use it after code changes, before QA, or whenever symptom treatment is suspected.
+---
+
+# clean-implementation-review
+
+## Purpose
+Evaluate implementation integrity.
+
+This skill answers:
+
+- was the task solved with a clean primary solution
+- was the root cause fixed or only masked
+- were unnecessary fallbacks, workarounds, guards, defaults, or shims introduced
+- were unnecessary parallel structures introduced
+- does the solution fit the existing architecture
+- is it maintainable or workaround-heavy
+
+## Runtime Contract
+Use `../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
+
+Clean-review-specific output must make the primary solution, fallbacks, workarounds, parallel structures, exit criteria, and next cleanup/review step visible.
+
+## Rules
+1. Clean primary solution before fallback.
+2. Root cause before symptom masking.
+3. Fallbacks are exceptions, not target architecture.
+4. Every retained fallback needs rationale, target state, and exit condition.
+5. No silent parallel structures.
+6. Brownfield fit is mandatory.
+7. Maintainability matters; "works somehow" is not enough.
+8. Async execute paths must not decide product rules again.
+9. Shared finalization or merge rules belong in one owner.
+
+## When To Use
+- after `CD+Tests`
+- before QA
+- when a solution contains many guards, defaults, or special paths
+- when wrappers or helper layers were introduced
+- when symptom treatment is suspected
+- when fallback, retry, or compatibility-shim logic was added
+- when code works but the architecture looks questionable
+
+## Inputs
+Use what is available:
+
+- Task Plan
+- Code Deliverables
+- changed files
+- tests and test results
+- `agdf-code-review` or Code Review Report
+- QA Report
+- Brownfield Analysis findings
+- PRD or SD architecture notes
+
+If evidence is missing, mark it explicitly.
+
+## Workflow
+1. Understand the intended change.
+2. Identify the primary implementation path.
+3. Identify fallbacks, guards, defaults, shims, retries, wrappers, and catch-all branches.
+4. Decide whether each is justified.
+5. Check for parallel ownership.
+6. Check Brownfield fit.
+7. Assess whether the implementation fixes the root cause.
+8. Assign a decision:
+   - `pass`
+   - `revise`
+   - `block`
+   - `not_applicable`
+
+## Output
+Use this compact structure:
+
+```text
+## Clean Implementation Review
+- decision:
+- primary_solution:
+- evidence:
+- fallbacks_retained:
+- workaround_or_shim_risk:
+- parallel_structure_risk:
+- brownfield_fit:
+- missing_evidence:
+- required_next_step:
+```
+
+## Pass / Revise / Block Guidance
+- `pass`: primary solution is clean, tested, and integrated with existing owners.
+- `revise`: solution works but contains avoidable fallback, unclear ownership, or missing evidence.
+- `block`: solution creates a second SoT, a second owner, unbounded fallback, or masks unresolved product semantics.
+
+## Forbidden
+This skill must not:
+
+- accept fallback-heavy logic as target architecture
+- hide unjustified workarounds
+- treat green tests as proof of solution integrity
+- decide final QA

package/generated/.github/skills/agdf-code-review/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: agdf-code-review
+description: Use this skill after code changes and before QA to produce the mandatory Code Review Report for correctness, regression, security, and maintainability findings in the actual diff. It standardizes the CR step without replacing TP review, clean review, or QA.
+---
+
+# code-review
+
+## Purpose
+Produce the mandatory Code Review Report (CR) for a relevant run.
+
+It answers:
+
+- whether the changed code shows functional defects, security issues, regression risks, or maintainability problems that matter
+- whether findings are blocking, revisable, or advisory
+- which concrete evidence in files, diffs, tests, or runtime observations supports each finding
+- which issues must be fixed before QA
+- whether Brownfield, TP, or clean-review follow-up remains open
+
+## Runtime Contract
+Use `../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
+
+Code-review-specific output must make actual findings, missing review scope, evidence strength, and the next required step visible.
+
+## Rules
+1. Review the actual diff and impacted code, not intent alone.
+2. Findings require concrete evidence.
+3. Prioritize correctness, safety, data integrity, compatibility, and maintainability over style.
+4. Do not generate style-only noise.
+5. Missing review scope or evidence must stay visible.
+6. Brownfield owners and existing conventions are binding unless deviation is justified.
+7. Distinguish blocking defects from fixable review findings.
+8. CR does not grant QA pass.
+
+## When To Use
+- after `CD+Tests`
+- before `QA`
+- when code changes exist
+- when multiple agents or contributors touched the same area
+- when a commit-near change needs explicit review evidence
+
+## Inputs
+Use what is available:
+
+- changed files and diff
+- affected neighbouring code
+- test/build results
+- Brownfield Analysis
+- Task Plan and TP Review
+- Clean Implementation Review
+- runtime or UI evidence
+- known risks or follow-up decisions
+
+If no code changes are present, do not invent a CR result.
+
+## Workflow
+1. Inspect the changed files and directly impacted neighbours.
+2. Check correctness, edge cases, and error paths.
+3. Check security, data handling, and state ownership risks.
+4. Check regression and compatibility risks.
+5. Check maintainability only where it creates real defect or change-risk exposure.
+6. Classify the overall result:
+   - `pass`
+   - `revise`
+   - `block`
+   - `not_applicable`
+7. Set exactly one required next step.
+
+## Output
+Use this compact structure:
+
+```text
+## Code Review
+- decision: pass | revise | block | not_applicable
+- findings:
+  - [severity] file/path - issue - evidence
+- missing_evidence:
+- risks:
+- required_next_step:
+```
+
+## Decision Guidance
+- `pass`: no meaningful review finding remains evident in reviewed scope.
+- `revise`: fixable correctness, regression, or maintainability issues remain.
+- `block`: a hard defect, security risk, data-integrity risk, or unresolved critical uncertainty remains.
+- `not_applicable`: no code changes were present for review.
+
+## Forbidden
+This skill must not:
+
+- decide final QA
+- accept a green build as sufficient review evidence
+- hide missing review scope
+- generate style-only findings
+- duplicate TP Review or QA as if they were the same step

package/generated/.github/skills/agdf-delivery-closeout/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: agdf-delivery-closeout
+description: Use this skill for the final delivery handoff after QA, OR, or UAT when a run should move toward commit, push, or PR. It standardizes commit-ready summaries, UAT-gated commit offers, and the next delivery step without replacing QA or OR decisions.
+---
+
+# delivery-closeout
+
+## Purpose
+Standardize the operational delivery closeout.
+
+It answers:
+
+- what operational delivery status applies after QA, OR, or UAT
+- whether a commit-ready Git summary should be provided
+- whether a commit should be actively offered after `Approval: UAT`
+- which next delivery step makes sense: commit, push, PR, rollout, or none
+- whether evidence-based technical follow-up remains useful
+- whether Context Graph follow-up from OR/QA remains open
+
+This skill does not replace `agdf-qa-gate`, `agdf-release-or`, user approvals, or gate decisions.
+
+## Runtime Contract
+Use `../agdf-runtime-contract.md` for closeout discipline, gate terms, Context Graph fields, and non-duplication rules.
+
+## Rules
+1. Delivery follows gate clarity.
+2. Never perform commit, push, or PR automatically.
+3. Use one handoff format:
+   - `Commit title`
+   - `Commit body`
+   - optional `Migration/Rollout note`
+4. `Approval: UAT` unlocks an active commit offer when code changes exist.
+5. No commit handoff for runs without code changes.
+6. Always include exactly one next step and one quality outlook.
+
+## When To Use
+- after `QA pass` with code changes
+- after OR when delivery handoff should be clean
+- after `Approval: UAT`
+- when the user asks for commit, push, or PR handoff
+
+Do not use as a substitute for `agdf-qa-gate`, `agdf-release-or`, or `agdf-gate-check`.
+
+## Inputs
+Use what is available:
+
+- QA Report
+- OR
+- current gate status
+- whether code changes exist
+- existing commit-ready summary
+- rollout or migration notes
+- open technical risks or documentation gaps
+- Context Graph impact from OR/QA/review
+
+If code-change status is unclear, do not claim a commit handoff.
+
+## Workflow
+1. Classify the closeout:
+   - `qa_pass_with_code`
+   - `qa_pass_without_code`
+   - `uat_approved_with_code`
+   - `uat_approved_without_code`
+   - `non_delivery_closeout`
+2. Derive Git handoff only when code changes exist.
+3. Set exactly one next delivery step:
+   - offer commit
+   - offer push
+   - offer PR
+   - no further delivery step
+   - run QA/review
+   - obtain UAT/approval
+   - perform documentation follow-up
+4. Set quality outlook:
+   - no further technical follow-up
+   - more tests
+   - refactoring
+   - documentation sharpening
+   - monitoring/runtime verification
+5. If `Approval: UAT` exists and code changes were delivered, actively offer the commit but do not run it.
+
+## Output
+For code-changing runs:
+
+```text
+Delivery status:
+Next step:
+Quality outlook:
+Commit title:
+Commit body:
+Migration/Rollout note:
+```
+
+For non-code runs:
+
+```text
+Delivery status:
+Next step:
+Quality outlook:
+```
+
+## Forbidden
+This skill must not:
+
+- decide QA pass
+- replace OR
+- execute commit, push, or PR
+- invent a commit handoff for non-code runs
+- imply new gate approvals

package/generated/.github/skills/agdf-gate-check/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: agdf-gate-check
+description: Use this skill when the active gate is unclear, when a later-gate artefact is requested, when an exact approval may be missing, or when the next permissible step must be determined. Use it before creating formal artefacts in Structured Delivery and whenever implicit consent might be mistaken for approval.
+---
+
+# gate-check
+
+## Purpose
+Determine the earliest blocking user approval gate and derive:
+
+- the active or blocking gate
+- whether the process is open or blocked
+- currently allowed outputs
+- currently forbidden outputs
+- the exact missing approval
+- the next permissible step
+
+This skill must not create later artefacts such as PRD, SD, TP, CD, CR, QA, or UAT when the gate does not allow them.
+
+## Runtime Contract
+Use `../agdf-runtime-contract.md` for gate terms, closeout discipline, and non-duplication rules.
+
+## Rules
+1. Fail closed when a required approval or artefact status is missing.
+2. The earliest blocking gate wins.
+3. A user approval is valid only as `Approval: <GateName>`.
+4. Treat `Freigabe: <GateName>` as a legacy alias only when reviewing older German runs.
+5. Implicit consent is not approval.
+6. Do not preview later artefacts while a gate blocks.
+7. Internal process steps are not user approval gates.
+8. OR-lite is allowed if it does not leak blocked content.
+9. SoT/runtime/product-semantics drift can trigger an early product gate, usually `UR`.
+
+## Gate Order
+User gates:
+
+`UR -> PRD -> SD -> TP -> QA -> UAT`
+
+Internal mandatory steps:
+
+`Brownfield Analysis -> CD+Tests -> CR -> OR`
+
+## When To Use
+- Structured Delivery before first artefact creation
+- unclear current gate
+- user says "continue" or similar without exact approval
+- code or a later-gate artefact is requested
+- implementation permission is unclear
+- QA, UAT, or release permission is unclear
+
+Not required for simple Quick Tasks without new product scope and without formal artefacts.
+
+## Inputs
+Use what is available:
+
+- current user request
+- existing exact approvals
+- status of UR, PRD, SD, TP
+- Brownfield Analysis status
+- CD+Tests, CR, QA, UAT status
+- signs of documentation/runtime/product-semantics drift
+
+If a status is not explicit, do not assume it is satisfied.
+
+## Workflow
+1. Check exact approvals.
+2. Check artefact status.
+3. Determine the earliest blocking user gate or internal mandatory step.
+4. Derive allowed and forbidden outputs.
+5. Name the exact missing approval, if any.
+6. If consent was only implicit, say it is not yet approval and provide the exact formula.
+
+## Output
+Keep the result short and operational:
+
+- **Current gate:** `<GateName or internal step>`
+- **Status:** `open | blocked`
+- **Allowed:** `<allowed outputs>`
+- **Forbidden:** `<forbidden outputs>`
+- **Missing approval:** `Approval: <GateName> | none`
+- **Next step:** `<single permissible next step>`
+
+## Forbidden
+This skill must not:
+
+- create PRD before UR approval
+- create SD before PRD approval
+- create TP while earlier gates block
+- perform full Brownfield Analysis unless explicitly requested
+- provide implementation snippets while implementation is gated
+- present QA or UAT as passed without evidence
+- present release as allowed without QA pass and UAT approval where required

package/generated/.github/skills/agdf-qa-gate/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: agdf-qa-gate
+description: Use this skill before any QA decision to determine whether implementation can be classified as pass, revise, or block based on TP coverage, Brownfield fit, solution integrity, evidence, and open blockers. Use it after CD+Tests, after reviews, and before UAT or release decisions.
+---
+
+# qa-gate
+
+## Purpose
+Make the formal QA gate decision.
+
+This skill is the only final QA decision point for `pass | revise | block`.
+
+It answers:
+
+- whether `QA pass` is allowed
+- whether the implementation must be revised
+- whether a hard blocker remains
+- whether relevant TP tasks are sufficiently verified
+- whether P0/P1 tasks are complete
+- whether Brownfield fit is sufficient
+- whether solution integrity is sufficient
+- whether blockers, critical risks, or missing evidence remain
+
+## Runtime Contract
+Use `../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
+
+QA-specific `decision` is exactly `pass | revise | block`.
+`pass` is allowed only when TP coverage, Brownfield fit, solution integrity, and relevant documentation/Context Graph impact are sufficiently evidenced.
+`sot_drift` must not pass silently as a warning.
+
+## Rules
+1. No QA pass without strong evidence.
+2. TP is the reference, not merely working code.
+3. P0/P1 gaps block `pass`.
+4. Brownfield fit is mandatory.
+5. UI surface integrity is mandatory for UI-impacting changes.
+6. Solution integrity is mandatory.
+7. Always output exactly one decision: `pass`, `revise`, or `block`.
+8. Open risks, missing tests, partial TP coverage, or side effects must be visible.
+
+## When To Use
+- after `CD+Tests`
+- after `agdf-code-review`
+- after `agdf-task-plan-review`
+- after `agdf-clean-implementation-review`
+- before UAT
+- before any claim that implementation is done, releasable, or QA-ready
+- when evidence from Brownfield, TP, or clean-review skills exists
+
+Important:
+
+- `CD+Tests` is implementation and test status only.
+- Without review evidence and TP coverage, `QA pass` is not allowed.
+
+## Inputs
+Use what is available:
+
+- approved TP and TP Review
+- Brownfield Analysis
+- Clean Implementation Review
+- `agdf-code-review` or Code Review Report
+- test/build results
+- documentation impact review
+- runtime or UI evidence
+- known blockers and risks
+
+If evidence is missing, lower the decision accordingly.
+
+## Workflow
+1. Confirm the relevant gate context.
+2. Verify TP coverage.
+3. Verify P0/P1 completion.
+4. Verify Brownfield fit.
+5. Verify solution integrity.
+6. Verify tests and evidence strength.
+7. Verify documentation and Context Graph impact if relevant.
+8. Decide:
+   - `pass`
+   - `revise`
+   - `block`
+9. State the single required next step.
+
+## Output
+Use this shape:
+
+```text
+## QA Gate
+- decision: pass | revise | block
+- evidence:
+- missing_evidence:
+- risks:
+- required_next_step:
+- impact_codes:
+```
+
+If Context Graph impact is relevant, include the fields from `../agdf-runtime-contract.md`.
+
+## Decision Guidance
+- `pass`: required TP tasks are done, evidence is strong, no blocking Brownfield or solution-integrity risk remains.
+- `revise`: implementation is plausible but missing evidence, partial tasks, UX gaps, or fixable integrity issues remain.
+- `block`: hard prerequisite, approval, product semantics, security/compliance, SoT drift, or critical behaviour is unresolved.
+
+## Forbidden
+This skill must not:
+
+- grant QA pass from a green build alone
+- hide partial task completion
+- replace UAT
+- treat missing reviews as completed
+- downgrade SoT drift to harmless warning

package/generated/.github/skills/agdf-release-or/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: agdf-release-or
+description: Use this skill at the end of every relevant run to produce a compact, auditable Orchestration Report. It summarizes gate status, delivered and intentionally not delivered work, TP coverage, Brownfield fit, solution integrity, open risks, and the next permissible step.
+---
+
+# release-or
+
+## Purpose
+Produce the Orchestration Report (OR) as the mandatory closeout for a relevant run.
+
+It reports:
+
+- current user gate
+- whether the run is `pass`, `revise`, `block`, or not yet QA-decided
+- what was delivered
+- what was intentionally not delivered
+- missing approvals
+- TP coverage status
+- Brownfield fit
+- solution integrity
+- documentation impact
+- Context Graph impact
+- open risks, blockers, retained fallbacks, and exit criteria
+- next permissible step
+- whether further quality follow-up is useful
+
+## Runtime Contract
+Use `../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
+
+OR-specific output must make gate status, delivered and intentionally not delivered content, missing approvals, missing evidence, risks, retained fallbacks, and the next permissible step visible.
+
+## Rules
+1. OR is always allowed and mandatory for relevant runs.
+2. OR is an audit report, not a blocking gate.
+3. Do not leak artefacts from blocked later gates.
+4. Use OR-lite when early gates block.
+5. Use OR-full only within the allowed scope.
+6. Report status, not marketing language.
+7. Name missing approvals, partial implementation, risks, fallbacks, Brownfield issues, and open defects.
+8. Retained fallbacks require visible exit criteria and cleanup path.
+9. End with the immediately permissible next step.
+10. `CD+Tests` is not completion.
+
+## When To Use
+- at the end of every relevant run
+- after artefact creation
+- when a gate blocks
+- after `CD+Tests`
+- after `agdf-code-review`
+- after QA
+- after UAT
+- whenever a compact audit closeout is needed
+
+## Inputs
+Use what is available:
+
+- current gate
+- existing approvals
+- artefacts created in this run
+- intentionally not delivered content
+- Task Plan
+- `agdf-task-plan-review`
+- `agdf-brownfield-analysis`
+- `agdf-clean-implementation-review`
+- `agdf-code-review`
+- QA Report
+- UAT Report
+- documentation impact review
+- Context Graph impact
+- known risks, defects, fallbacks, and open questions
+- test/build status and relevant metrics
+
+If information is missing, state the gap instead of guessing.
+
+## Workflow
+1. Determine the current gate and earliest blocker.
+2. Determine report depth:
+   - `OR-lite`: gate status, allowed/forbidden outputs, missing approval, next step
+   - `OR-full`: also delivered artefacts, TP coverage, Brownfield fit, solution integrity, risks, fallbacks, QA/UAT status
+3. Record delivered vs intentionally not delivered content.
+4. Summarize TP coverage if a TP exists.
+5. Summarize Brownfield fit and solution integrity if reviewed.
+6. Summarize tests and verification.
+7. Summarize documentation and Context Graph impact if relevant.
+8. Name retained fallbacks and exit criteria.
+9. Set exactly one next permissible step.
+10. Set exactly one quality outlook.
+11. Add a commit-ready handoff only when code changes exist and the delivery state allows it.
+
+## Output
+Use a compact structure:
+
+```text
+## OR
+- gate:
+- status:
+- delivered:
+- intentionally_not_delivered:
+- evidence:
+- missing_evidence:
+- risks:
+- retained_fallbacks:
+- required_next_step:
+- quality_outlook:
+```
+
+When Context Graph impact is relevant, include the fields from `../agdf-runtime-contract.md`.
+
+For code-changing closeouts that are commit-near, append:
+
+```text
+Commit title:
+Commit body:
+Migration/Rollout note:
+```
+
+## Forbidden
+This skill must not:
+
+- decide QA in place of `agdf-qa-gate`
+- call `CD+Tests` complete, QA-ready, or release-ready
+- hide missing approvals
+- provide later-gate content while an earlier gate blocks
+- execute commit, push, or PR actions

package/generated/.github/skills/agdf-runtime-contract.md

@@ -0,0 +1,73 @@
+# AGDF Runtime Contract
+
+This contract centralizes recurring runtime rules for AGDF skills.
+It is the operational reference for skill outputs, but it is not a second copy of the framework documentation.
+
+## Mode Selection
+
+| Mode | Default | Escalate When |
+|---|---|---|
+| Quick Task Mode | small questions, reviews, debugging, local fixes without new product semantics | a new user capability, architecture/policy/persistence impact, formal artefacts, or approvals are involved |
+| Structured Delivery Mode | formal delivery runs, gate-relevant work, release-critical changes | always use gate discipline, internal reviews, and OR |
+
+Quick Task Mode must not become ritual gate overhead.
+Structured Delivery must not bypass missing approvals.
+
+## Gate Rules
+
+- User gates: `UR -> PRD -> SD -> TP -> QA -> UAT`
+- Internal mandatory steps: `Brownfield Analysis -> CD+Tests -> CR -> OR`
+- Exact approval formula: `Approval: <GateName>`
+- Legacy alias: `Freigabe: <GateName>` may be accepted when reviewing older German runs, but all new outputs must use `Approval: <GateName>`.
+- Implicit consent is not approval.
+- The earliest blocking gate wins.
+- `CD+Tests` is implementation and test status only, not a delivery signal.
+- `agdf-code-review` standardizes the mandatory `CR` step, but does not replace QA.
+- `agdf-qa-gate` decides final `pass | revise | block`.
+- `agdf-release-or` reports the run, but does not replace QA.
+
+## Quality Contract Output
+
+Structured Delivery skills use this shape when relevant:
+
+- `decision`: `pass | revise | block | not_applicable`
+- `evidence`: concrete artefacts, files, tests, logs, diffs, or observations
+- `missing_evidence`: missing proof needed for a stronger claim
+- `risks`: remaining risks, assumptions, fallbacks, drift, or blockers
+- `required_next_step`: exactly the next clean step
+- `impact_codes`: affected Quality Contract codes, if the target repo has a registry
+
+A skill may briefly remind this shape, but must not duplicate a complete code or rule matrix.
+
+## Context Graph Output
+
+When a run affects project memory or a Context Graph, use:
+
+- `Situation:` short plain-language summary when the impact is non-trivial
+- `context_graph_impact`: `none | link_only | update_existing_node | new_node_required | sot_drift`
+- `context_graph_refs`
+- `context_graph_required_action`: `none | link | update | create | resolve_drift`
+- `context_graph_gate_effect`: `none | warning | revise | block`
+- `context_graph_evidence`
+
+Do not create a new node for a mere version, a general chat summary, or a local observation without a concrete next clean step.
+`sot_drift` must not pass silently as a warning.
+
+## Skill Output
+
+Every skill output should be as short as possible and as concrete as needed.
+It must distinguish:
+
+- facts
+- evidence
+- assumptions
+- interpretations
+- missing evidence
+- the next permissible step
+
+## Do Not Duplicate
+
+The explanatory framework lives in `docs/`.
+The operating philosophy lives in `plugin/meta/agdf-constitution.md`.
+The principles live in `plugin/meta/agdf-tenets.md`.
+This contract is only the compact runtime interface for skills.

package/generated/.github/skills/agdf-task-plan-review/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: agdf-task-plan-review
+description: Use this skill after code changes and before QA to verify whether the approved Task Plan was actually fulfilled. It checks each task_id against implementation, acceptance criteria, tests, visible evidence, and deviations, and provides TP coverage for QA.
+---
+
+# task-plan-review
+
+## Purpose
+Verify whether implementation actually satisfies the approved Task Plan.
+
+For each relevant task, this skill determines:
+
+- whether the task is fully, partially, or not completed
+- which acceptance criteria are done, partial, missing, or not verifiable
+- which files, tests, runtime evidence, or UI evidence support the finding
+- evidence strength
+- which gaps must be handed to `agdf-qa-gate`
+
+This skill provides TP coverage. It is not the final QA decision.
+
+## Runtime Contract
+Use `../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
+
+TP-specific output must evaluate every relevant `task_id` with completion status, AC coverage, evidence, missing evidence, and QA-relevant gaps.
+If `context_graph_required_action` is not `none`, the affected task is complete only if follow-up, evidence, or an intentionally open gap is visible.
+
+## Rules
+1. The Task Plan is the reference, not plausible code.
+2. No assumptions without evidence.
+3. Evaluate each relevant `task_id` individually.
+4. `fully_done` requires strong evidence.
+5. A green build alone does not prove TP completion.
+6. UI/state/render/recovery tasks need visible evidence, not only code.
+7. Partial implementation must be marked `partially_done`.
+8. P0/P1 gaps must be handed to QA.
+9. Out-of-scope changes must be reported.
+10. When evidence is unclear, fail closed to at least `partially_done`.
+
+## Clarifications
+### TP Slice Before Target State
+If the TP explicitly defines a preparatory, additive, or limited slice, evaluate that exact scope.
+`fully_done` is allowed for a completed slice even if the larger target state remains open.
+
+### Missing Priorities
+If no priorities are defined, do not invent them. Mark the gap and treat QA relevance conservatively.
+
+### Missing Acceptance Criteria
+If ACs are unclear, derive only obvious expectations from title, goal, and scope. Mark AC basis as incomplete and lower evidence confidence as needed.
+
+## When To Use
+- after `CD+Tests`
+- before `QA`
+- when TP completion is unclear
+- when the user asks for TP fulfilment
+- when UI/state/runtime invariants are affected
+- when several agents or work steps touched the same TP
+
+## Inputs
+Use what is available:
+
+- Task Plan
+- `task_id`, `story_id`, priorities
+- acceptance criteria or success goals
+- changed files
+- tests and test results
+- build results
+- runtime/UI evidence
+- known deviations and scope decisions
+
+If TP or relevant tasks are missing, do not claim reliable TP coverage.
+
+## Output
+Use this compact structure:
+
+```text
+## TP Coverage
+| task_id | status | evidence | missing_evidence | QA impact |
+|---|---|---|---|---|
+
+## Summary
+- fully_done:
+- partially_done:
+- not_done:
+- out_of_scope_changes:
+- risks:
+- required_next_step:
+```
+
+Completion status:
+
+- `fully_done`
+- `partially_done`
+- `not_done`
+
+AC status:
+
+- `done`
+- `partial`
+- `missing`
+- `not_verifiable`
+
+Evidence confidence:
+
+- `high`
+- `medium`
+- `low`
+
+## Forbidden
+This skill must not:
+
+- decide final QA
+- mark tasks fully done from code existence alone
+- hide partial work
+- upgrade missing evidence into confidence
+- reinterpret the TP scope

package/{templates → generated}/AGENTS.md

@@ -44,6 +44,7 @@ Evidence overrides assumptions and memory. If evidence is missing, state the unc
 | `agdf-brownfield-analysis` | before non-trivial implementation in existing systems | clarifies reuse, owners, risks |
 | `agdf-task-plan-review` | after implementation and before QA, verify TP coverage | no final QA decision |
 | `agdf-clean-implementation-review` | inspect workarounds, fallbacks, parallel structures, or symptom fixes | not a TP or QA substitute |
+| `agdf-code-review` | mandatory CR step after code changes, focused on defects, regression, and security findings | does not replace TP review, clean review, or QA |
 | `agdf-qa-gate` | final QA decision | only instance for `pass | revise | block` |
 | `agdf-release-or` | auditable closeout for every relevant run | not a QA substitute |
 | `agdf-delivery-closeout` | commit/PR-near handoff after QA/OR/UAT | never performs VCS actions automatically |
@@ -52,7 +53,7 @@ Select exactly one primary skill first. Add more only when they cover a distinct
 
 ## Skill Contract
 For repeated output, gate, Quality Contract, and Context Graph rules, use:
-`plugin/meta/agdf-runtime-contract.md`
+the repository-local `agdf-runtime-contract.md` artifact.
 
 Skills may include short runtime reminders, but must not carry a second complete rule or code table.
 

package/package.json

@@ -1,18 +1,20 @@
 {
   "name": "create-agdf",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Bootstrap AGDF for GitHub Copilot, Claude Code, or both.",
   "type": "module",
   "files": [
     "bin",
-    "templates",
+    "generated",
     "README.md"
   ],
   "bin": {
     "create-agdf": "./bin/create-agdf.js"
   },
   "scripts": {
-    "smoke-test": "node ./scripts/smoke-test.js"
+    "sync-package-assets": "node ./scripts/sync-package-assets.js",
+    "smoke-test": "npm run sync-package-assets && node ./scripts/smoke-test.js",
+    "prepack": "npm run sync-package-assets"
   },
   "keywords": [
     "agdf",

package/templates/.github/copilot-instructions.md

@@ -1,31 +0,0 @@
-# AGDF for GitHub Copilot
-
-This repository supports GitHub Copilot CLI and the Copilot Coding Agent through checked-in repository instructions.
-
-## Primary instruction sources
-
-1. Follow `AGENTS.md` as the main operating model.
-2. Use `plugin/meta/agdf-runtime-contract.md` for repeated gate, quality-contract, and closeout output rules when this repository also contains the AGDF runtime files.
-3. Reuse the AGDF skill names as prompt entrypoints: `agdf-gate-check`, `agdf-brownfield-analysis`, `agdf-task-plan-review`, `agdf-clean-implementation-review`, `agdf-qa-gate`, `agdf-release-or`, `agdf-delivery-closeout`.
-
-## Working mode
-
-- Default to **Quick Task Mode** for small questions, reviews, debugging, and local fixes without new product semantics.
-- Escalate to **Structured Delivery Mode** for new capabilities, architecture or policy changes, persistence changes, release-critical work, or formal artefacts.
-
-## Copilot prompt entrypoints
-
-Use natural-language prompts such as:
-
-- `Run an AGDF gate check for this request.`
-- `Perform an AGDF brownfield analysis before implementation.`
-- `Review the completed work against the AGDF task plan expectations.`
-- `Make the AGDF QA gate decision from the available evidence.`
-
-## Rules
-
-- Respect the gate order and exact approval formula from `AGENTS.md`.
-- Do not treat implicit consent as approval.
-- Prefer evidence over assumptions.
-- In brownfield work, reuse before create and avoid silent parallel structures.
-- After relevant work, include exactly one `Next step:` and exactly one `Quality outlook:`.