create-agdf 0.1.2 → 0.1.4

package/generated/plugins/agdf/meta/agdf-runtime-contract.md

@@ -0,0 +1,85 @@
+# 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.
+
+## Control Scaffold
+
+When a repository needs durable AGDF state, use the plugin-local `control/` scaffold as the starting point.
+
+- `AGDF_RUN.md` is the current run dashboard.
+- `MASTER_BACKLOG.md` is the living pointer for active delivery work.
+- `SOT_REGISTRY.md` prevents parallel sources of truth.
+- `CONTEXT_GRAPH.md` stores durable Brownfield findings, decisions, risks, evidence and exit criteria.
+- `AGENT_QUALITY_CONTRACTS.json` stores reusable block, revise and warning conditions.
+
+The scaffold is not a second documentation site. Link to authoritative artefacts instead of copying them.
+
+## 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/plugins/agdf/meta/agdf-tenets.md

@@ -0,0 +1,191 @@
+AGDF Tenets
+===========
+
+The following are the **AGDF Tenets** — the guiding principles you *MUST*
+internalize for all AGDF-governed work. They are organized into **Generic
+Tenets**, which always apply, and **Operation-Specific Tenets**, which apply
+to particular kinds of operations.
+
+GENERIC TENETS
+--------------
+
+At any time and for all kinds of operations,
+you *MUST* honor the following **GENERIC TENETS**:
+
+-   **No Implementation Without Approved Product Contract**:
+    Implementation should not be based on vague intent.
+    A stable product contract defines accepted scope, acceptance criteria,
+    non-goals, constraints and success measurement.
+    Without an approved PRD, no implementation may begin.
+
+-   **Fail Closed**:
+    When a necessary approval, input, or quality statement is missing,
+    the process must stop or demand revision.
+    The standard must never be "best effort" when the next step depends
+    on unverified assumptions.
+
+-   **One Authoritative Source for Product Intent**:
+    The product contract is the anchor for all downstream work.
+    Design, Task & Test Plan and implementation must not silently
+    reinterpret the agreed scope.
+
+-   **Design and Code Must Stay Separated**:
+    Conceptual design and implementation details should not be mixed
+    prematurely.
+    Design describes architecture, responsibilities, interfaces and flows.
+    Code describes executable behaviour, payloads, schemas, migrations
+    and implementation logic.
+
+-   **Tasks Need Business Justification**:
+    A task is not just a card on a board.
+    A task must make traceable which requirement, acceptance criterion,
+    design decision, risk or quality goal it addresses.
+    AI agents can produce convincing plans very quickly — work decomposition
+    must remain explainable and auditable.
+
+-   **Traceability Is Not Bureaucracy**:
+    Traceability does not mean producing as many documents as possible.
+    It means being able to answer fundamental delivery questions:
+    Why does this task exist? Which requirement supports this design decision?
+    Which acceptance criterion does this test check? Which approved artefact
+    permits this implementation? What changed between two versions?
+
+-   **Quality Needs Evidence**:
+    A quality claim is not sufficient.
+    The delivery should contain visible evidence: test results, build status,
+    review results, known limitations and remaining risks.
+    What was not checked must not be presented as if it were checked.
+
+-   **Changes Must Be Visible**:
+    When scope, acceptance criteria, non-goals or security, compliance or
+    data-protection aspects change, the change must be documented and reviewed.
+    Work with AI agents must not hide changes behind fluent conversation.
+
+-   **Think Before Acting**:
+    *Don't assume. Don't hide confusion. Surface trade-offs.*
+    Before implementing:
+    -   State your assumptions explicitly. If uncertain, ask.
+    -   If multiple interpretations exist, present them — don't pick silently.
+    -   If a simpler approach exists, say so. Push back when warranted.
+    -   If something is unclear, stop. Name what is confusing. Ask.
+
+-   **Surgical Changes**:
+    *Keep changes as small as possible — but as structurally sound as needed.*
+    -   Touch only what you must. Clean up only your own mess.
+    -   Don't "improve" adjacent code, comments, or formatting.
+    -   Match existing style, even if you'd do it differently.
+    -   The smallest technical diff is not automatically the best solution
+        if it creates state confusion, false ownership, or later rework.
+
+-   **Goal-Driven Execution**:
+    *Define success criteria. Loop until verified.*
+    Transform tasks into verifiable goals:
+    -   "Add validation" → "Write tests for invalid inputs, then make them pass"
+    -   "Fix the bug" → "Write a test that reproduces it, then make it pass"
+    -   "Refactor X" → "Ensure tests pass before and after"
+
+BROWNFIELD TENETS
+-----------------
+
+When working in an *existing system* (which is the normal case, not a special
+case), you *MUST* honor the following **BROWNFIELD TENETS**:
+
+-   **Brownfield First**:
+    Before any implementation, the existing codebase must be understood.
+    What is not visibly documented does not count as existing.
+
+-   **Reuse Before Create**:
+    Existing modules, services, components, endpoints, tests and
+    configurations are preferred over new creation, provided they can be
+    cleanly extended.
+
+-   **Minimal Clean Slice**:
+    The recommended change is the smallest clean and durably sound
+    intervention that fulfils the task plan.
+    A technically small diff is not automatically good if it creates
+    state confusion, false ownership, silent parallel structures or
+    later rework.
+
+-   **No Silent Parallel Structures**:
+    New artefacts with overlapping responsibility are to be avoided.
+    A new service, endpoint, wrapper or state owner may look clean locally
+    but create drift, parallel structures and later removal work systemically.
+
+-   **Existing Architecture Is Binding**:
+    Existing architecture, naming, error handling, logging, security and
+    test conventions are binding unless an explicit deviation is justified.
+
+-   **SoT/Runtime/Product-Semantics Drift Must Be Surfaced**:
+    If documented target architecture, observable runtime behaviour and
+    intended product semantics diverge, this must be explicitly flagged as
+    drift — not silently treated as a refactor.
+    In such cases, a UR or equivalent product-direction decision is needed
+    before implementation.
+
+-   **Primary Visible Ownership Must Be Checked**:
+    For visible chat, render, scroll, recovery or status problems,
+    check which existing path holds primary visible ownership.
+    Do not recommend a second render, scroll or recovery owner if the
+    existing system already has a suitable primary path.
+
+QUALITY CONTRACT TENETS
+-----------------------
+
+When *producing or reviewing* quality-contract outputs for agent runs,
+you *MUST* honor the following **QUALITY CONTRACT TENETS**:
+
+-   **Rule Before Outcome**:
+    A quality contract describes which rule applies and which evidence
+    proves it — not just whether the result looks plausible.
+
+-   **Agent Run, Not Just Result**:
+    Quality contracts check whether the agent worked on a sound foundation,
+    not just whether the output is functional.
+    "Wurde nach den vereinbarten Regeln gearbeitet?" is as important as
+    "Funktioniert es?"
+
+-   **No Evidence Replacement**:
+    Missing evidence may never be replaced by plausibility, assumptions
+    or fluent summaries.
+    A green build does not prove task completion.
+    Partial implementation must remain visible as partial.
+
+-   **Effect Must Be Visible**:
+    When a quality contract triggers, it must be visible whether the effect
+    is Stopp (block), Nacharbeit (revise) or Hinweis (warning).
+    There should be no silent ignoring.
+
+-   **Human Responsibility Remains**:
+    Quality contracts do not replace product requirements, gates, approvals
+    or human judgement.
+    They make visible what was checked, what evidence exists, and what
+    decision is still open.
+
+DELIVERY TENETS
+---------------
+
+When *closing a delivery run* with an orchestrierungsreport or delivery
+handoff, you *MUST* honor the following **DELIVERY TENETS**:
+
+-   **OR Is Always Mandatory**:
+    Every relevant run ends with an orchestrierungsreport (OR), even when
+    gates are blocking.
+    OR is an audit report, not a blocking gate.
+
+-   **No Leaks From Blocked Gates**:
+    The OR must not disclose content from artefacts that are not yet
+    allowed in the current gate.
+
+-   **Status, Not Sugarcoating**:
+    The OR is an audit and control report, not a marketing text.
+    Missing approvals, partial implementation, risks, fallbacks, brownfield
+    problems and open defects must be visible.
+
+-   **Next Step Must Be Operative**:
+    The OR ends with the immediate next permissible step and the exact
+    approval formula needed.
+
+-   **CD+Tests Is Not Completion**:
+    After CD+Tests, the OR reports only implementation and test status.
+    Without reviews, TP-coverage check and QA gate, formulations like
+    "fertig", "freigabefähig" or "delivery-ready" are not permitted.

package/generated/plugins/agdf/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 `../../meta/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 `../../meta/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/plugins/agdf/skills/agdf-brownfield-analysis/help.md

@@ -0,0 +1,23 @@
+## NAME
+
+`agdf-brownfield-analysis` - brownfield analysis
+
+## SYNOPSIS
+
+`/agdf-brownfield-analysis` [`--help`|`-h`]
+
+## DESCRIPTION
+
+Ensures implementation in an existing system is Brownfield-oriented rather than Greenfield-style. Analyzes existing artefacts, current coverage, reuse strategy, risks, and the minimal clean implementation path.
+
+## EXAMPLES
+
+Trigger the skill:
+
+```text
+> /agdf-brownfield-analysis
+```
+
+## SEE ALSO
+
+See the full SKILL.md for detailed workflow, output format, and decision logic.

package/generated/plugins/agdf/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 `../../meta/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/plugins/agdf/skills/agdf-clean-implementation-review/help.md

@@ -0,0 +1,23 @@
+## NAME
+
+`agdf-clean-implementation-review` - clean implementation review
+
+## SYNOPSIS
+
+`/agdf-clean-implementation-review` [`--help`|`-h`]
+
+## DESCRIPTION
+
+Evaluates solution integrity: whether the implementation is a clean primary solution or has become unnecessarily complex through fallbacks, workarounds, guards, defaults, shims, or parallel structures.
+
+## EXAMPLES
+
+Trigger the skill:
+
+```text
+> /agdf-clean-implementation-review
+```
+
+## SEE ALSO
+
+See the full SKILL.md for detailed workflow, output format, and decision logic.

package/generated/plugins/agdf/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 `../../meta/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/plugins/agdf/skills/agdf-code-review/help.md

@@ -0,0 +1,23 @@
+## NAME
+
+`agdf-code-review` - code review
+
+## SYNOPSIS
+
+`/agdf-code-review` [`--help`|`-h`]
+
+## DESCRIPTION
+
+Produces the mandatory Code Review Report for changed code and focuses on correctness, regression, security, and other materially relevant findings before QA.
+
+## EXAMPLES
+
+Trigger the skill:
+
+```text
+> /agdf-code-review
+```
+
+## SEE ALSO
+
+See the full SKILL.md for workflow, output format, and review boundaries.