vgxness 1.13.0 → 1.14.0

package/docs/sdd-flow.md

@@ -0,0 +1,403 @@
+# SDD Flow
+
+> Spanish version: [Flujo SDD](./sdd-flow.es.md).
+
+> **Scope:** this document explains the practical end-to-end SDD flow in VGXNESS: from a human intent, through planning artifacts, implementation progress, verification, and archive. It is an operator-oriented companion to [Architecture](./architecture.md), [Safety](./safety.md), [CLI](./cli.md), and [MCP tools](./mcp.md).
+
+VGXNESS treats SDD as product state, not just agent prompting. Each phase produces a local SQLite-backed artifact, and phase advancement is gated by explicit readiness and, where required, explicit human acceptance.
+
+The canonical SDD phases are:
+
+```text
+explore → proposal → spec → design → tasks → apply-progress → verify → archive
+```
+
+## Mental model
+
+```text
+Human intent
+  ↓
+OpenCode conversation / CLI operator action
+  ↓
+VGXNESS MCP or CLI surface
+  ↓
+Control plane services
+  ↓
+SQLite-backed SDD artifacts, runs, memory, and checkpoints
+```
+
+The important separation is:
+
+```text
+Conversation ≠ state
+Draft ≠ acceptance
+Plan ≠ execution
+Preflight ≠ automatic permission
+Provider status ≠ provider config write
+CLI/MCP surface ≠ duplicated business rules
+```
+
+## 1. Human intent
+
+The workflow starts when the human states an objective, usually inside OpenCode after VGXNESS MCP has been installed.
+
+Example:
+
+```text
+Improve the interrupted-run recovery flow so VGXNESS can suggest how to continue safely.
+```
+
+VGXNESS should not jump straight to code for substantial changes. The safe path is to inspect the current SDD state and choose the next valid phase.
+
+Useful surfaces include:
+
+```text
+sdd_status
+sdd_next
+sdd_continue
+agent_resolve
+agent_activate
+```
+
+The CLI equivalents are useful for setup, diagnostics, recovery, and scripting:
+
+```bash
+vgxness sdd status --project <project> --change <change>
+vgxness sdd next --project <project> --change <change>
+vgxness sdd continue --project <project> --change <change>
+```
+
+## 2. `explore`: understand before choosing a solution
+
+Goal: investigate the problem, current code boundaries, prior decisions, risks, and possible approaches without committing to an implementation.
+
+Typical questions:
+
+- Where does the relevant logic live?
+- Which CLI and MCP tools already exist?
+- Which services own the domain rule?
+- What safety or storage constraints apply?
+- What risks would make the change hard to review?
+
+For interrupted-run recovery, exploration might inspect:
+
+```text
+src/runs/*
+src/sdd/*
+src/mcp/control-plane.ts
+src/cli/commands/*
+docs/*
+test/*
+```
+
+The phase artifact is saved under the canonical topic key:
+
+```text
+sdd/{change}/explore
+```
+
+An agent may mark the artifact ready, but readiness is not acceptance.
+
+## 3. Human acceptance of `explore`
+
+VGXNESS deliberately separates generated content from human approval:
+
+```text
+draft / ready ≠ accepted
+```
+
+Only a human acceptance decision should advance governance-gated downstream work. This prevents an agent from silently approving its own direction.
+
+CLI example:
+
+```bash
+vgxness sdd accept-artifact --project <project> --change <change> --phase explore
+```
+
+## 4. `proposal`: choose the product direction
+
+Goal: define what change should happen and why.
+
+A good proposal answers:
+
+- What problem are we solving?
+- Who benefits?
+- What is in scope?
+- What is explicitly out of scope?
+- What risks or tradeoffs exist?
+- How will success be recognized?
+
+Example proposal summary:
+
+```text
+Add a read-only continuation surface for interrupted runs that combines failed/blocked/needs-human runs, the last checkpoint, the associated SDD phase, and a safe recommended next action.
+```
+
+This is still direction-setting, not implementation.
+
+## 5. Human acceptance of `proposal`
+
+The proposal is the main scope contract. If it is too broad, implementation and review become risky.
+
+Recommended reviewer question:
+
+```text
+Can this be reviewed as one coherent slice, or should it be split?
+```
+
+For example, a safer first slice may be:
+
+```text
+Read-only interrupted-run diagnosis before any automatic recovery or provider execution.
+```
+
+After exact proposal acceptance, downstream draft planning can be generated, but those artifacts remain drafts until reviewed and accepted according to governance.
+
+## 6. `spec`: define observable behavior
+
+Goal: specify what the system must do without overfitting to implementation details.
+
+For interrupted-run recovery, a spec might require:
+
+- Runs with `failed`, `blocked`, or `needs-human` status are listed as recovery candidates.
+- Each candidate includes run id, project, workflow, phase, status, latest checkpoint, failure or blocker reason, and a recommended next action.
+- Empty state is explicit when no interrupted runs exist.
+- The surface is read-only and does not resume providers or mutate run state.
+
+Specs should include edge cases, for example:
+
+- many interrupted runs;
+- runs with no checkpoints;
+- runs from another project;
+- runs linked to already-accepted SDD phases;
+- incomplete or inconsistent stored metadata.
+
+## 7. `design`: decide how to build it
+
+Goal: connect the spec to the existing architecture.
+
+A useful design identifies:
+
+- service boundaries;
+- repository/query changes;
+- CLI and MCP surfaces;
+- schema additions;
+- renderer behavior;
+- tests;
+- migration needs, if any;
+- safety invariants.
+
+Example design sketch:
+
+```text
+Add a run-resume candidate service backed by the runs repository.
+Expose read-only MCP tools for candidate listing and inspection.
+Expose a CLI recovery/status command that uses the same service.
+Keep recommendation generation non-mutating.
+```
+
+Architecture rules to preserve:
+
+- CLI and MCP should share domain services.
+- Renderers should not reimplement business rules.
+- Read-only tools must remain non-mutating.
+- Provider config writes require explicit human consent.
+- SDD artifacts stay SQLite-backed; do not create `openspec/`.
+
+## 8. `tasks`: make the design reviewable
+
+Goal: break the design into small implementation steps.
+
+Example task breakdown:
+
+```text
+1. Add repository query for interrupted runs.
+2. Add a resume-candidate service.
+3. Add MCP schema and read-only tools.
+4. Add CLI command or extend the existing recovery/status surface.
+5. Add renderer output for empty, single, and many-candidate states.
+6. Add focused service tests.
+7. Add CLI/MCP contract tests.
+8. Update docs if user-facing behavior changes.
+```
+
+Good tasks are small, testable, and easy to review.
+
+## 9. `apply-progress`: implement with traceable progress
+
+Goal: perform the code change while recording what changed, what remains, and what evidence exists.
+
+Before implementation, check review size and risk:
+
+- Does the change touch multiple subsystems?
+- Does it alter storage or migrations?
+- Does it change MCP schemas?
+- Does it change safety behavior?
+- Is the diff too large for one review?
+
+If the change is too broad, split it before implementation.
+
+During implementation, `apply-progress` should capture:
+
+- completed work;
+- changed files or modules;
+- pending tasks;
+- test results;
+- known blockers;
+- deviations from the accepted design.
+
+`apply-progress` is a progress record, not proof that the implementation is correct.
+
+## 10. Preflight for risky operations
+
+VGXNESS uses preflight checks to keep risky operations explicit.
+
+Examples of risky categories:
+
+```text
+implementation-edit
+shell
+test-run
+install
+git-write
+provider-tool
+secrets
+external-directory
+```
+
+Conceptual MCP example:
+
+```text
+run_preflight({
+  category: "test-run",
+  operation: "bun run verify:test",
+  workflow: "sdd",
+  phase: "apply-progress"
+})
+```
+
+Preflight is advisory/planning control. It does not mean the operation is automatically approved or executed.
+
+## 11. `verify`: check the implementation independently
+
+Goal: verify the implementation against the accepted spec and design, preferably with a fresh reviewer/agent context for non-trivial changes.
+
+Verification should check:
+
+- the spec is satisfied;
+- design boundaries were respected or deviations are justified;
+- relevant tests pass;
+- read-only surfaces did not become mutating;
+- provider setup/config writes still require explicit consent;
+- storage, CLI, and MCP behavior remain consistent.
+
+Typical repository verification commands include:
+
+```bash
+bun run verify:typecheck
+bun run verify:test
+bun run verify:bun-sqlite
+bun run package:bun:evidence
+```
+
+Not every small docs or UI copy change needs the full suite. Storage, CLI/MCP schema, provider setup, or package changes deserve stricter verification.
+
+## 12. `archive`: close the change with durable context
+
+Goal: preserve what happened so future work can recover context without rereading the entire thread or diff.
+
+An archive artifact should include:
+
+- final outcome;
+- user-visible behavior changed;
+- key files or modules touched;
+- verification performed;
+- residual risks;
+- follow-up work;
+- rollback or recovery notes, if relevant.
+
+Example archive summary:
+
+```text
+Change: recover-runs
+Outcome: implemented a read-only interrupted-run recovery surface.
+Verification: typecheck and focused service/CLI tests passed.
+Residual risk: full package evidence was not run locally.
+Follow-up: consider TUI integration after the CLI/MCP flow stabilizes.
+```
+
+## Tool-flow sketch
+
+Inside OpenCode, the flow usually looks like this conceptually:
+
+```text
+sdd_status
+  ↓
+sdd_continue
+  ↓
+agent_activate(explore)
+  ↓
+sdd_save_artifact(explore)
+  ↓
+sdd_ready(explore)
+  ↓
+human accepts explore
+  ↓
+agent_activate(proposal)
+  ↓
+sdd_save_artifact(proposal)
+  ↓
+sdd_ready(proposal)
+  ↓
+human accepts proposal
+  ↓
+agent_activate(spec)
+  ↓
+agent_activate(design)
+  ↓
+agent_activate(tasks)
+  ↓
+human reviews/accepts gated artifacts
+  ↓
+agent_activate(apply)
+  ↓
+run_preflight(...)
+  ↓
+sdd_save_artifact(apply-progress)
+  ↓
+agent_activate(verify)
+  ↓
+sdd_save_artifact(verify)
+  ↓
+archive
+```
+
+## Why the flow exists
+
+A naive agentic workflow is:
+
+```text
+read code → edit code → run tests → say done
+```
+
+VGXNESS uses SDD to make that safer:
+
+```text
+understand objective
+  ↓
+choose scope
+  ↓
+specify behavior
+  ↓
+design the change
+  ↓
+split into tasks
+  ↓
+implement with preflight and progress tracking
+  ↓
+verify independently
+  ↓
+archive durable context
+```
+
+The upfront structure costs a little time, but it reduces hidden scope creep, unreviewable diffs, unsafe automation, and lost context.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vgxness",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "CLI and MCP control plane for guided AI-agent workflows, SDD, memory, and OpenCode setup.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {

package/seeds/skills/skill-seed-v1.json

@@ -65,6 +65,48 @@
       "version": "2026-05-20.v1",
       "content": "# vgxness-sdd-archive\n\nRole: Archive the completed SDD change after verification and human-controlled acceptance flow.\n\nOutput: final outcome, changed files, verification evidence, decisions, follow-ups, and durable summary.\n\nConfirm before writes beyond requested archive artifacts. Do not mutate provider config or install provider-native skills.\n\nBoundary: This is VGXNESS registry/context skill content only. It is not a provider-native OpenCode skill, must not be installed into .opencode, must not require skills.paths, and must not load remote content.",
       "metadata": { "ownedBy": "vgxness", "kind": "registry-context-skill", "nativeProviderSkill": false, "workflow": "sdd", "phase": "archive" }
+    },
+    {
+      "name": "vgxness-workflow-selection",
+      "description": "Chooses the lightest safe VGXNESS workflow for an operator intent.",
+      "version": "2026-06-16.v1",
+      "content": "# vgxness-workflow-selection\n\nRole: Choose the lightest workflow that safely matches the user's intent, risk, and review cost.\n\nUse explore for answers or investigation, debug for diagnosis, quickfix for small local low-risk edits, plan for non-mutating planning, build for clear scoped implementation, and SDD only for large, architectural, cross-surface, persistent, security-sensitive, provider-config, permission, or hard-to-review changes.\n\nOutput: recommended workflow, reason, risks, whether clarification is needed, and the smallest safe next step.\n\nBoundary: This is VGXNESS registry/context skill content only. It is not a provider-native OpenCode skill, must not be installed into .opencode, must not require skills.paths, and must not load remote content.",
+      "metadata": { "ownedBy": "vgxness", "kind": "registry-context-skill", "nativeProviderSkill": false, "category": "workflow-selection" }
+    },
+    {
+      "name": "vgxness-git-safety",
+      "description": "Protects user work and repository integrity during git-related operations.",
+      "version": "2026-06-16.v1",
+      "content": "# vgxness-git-safety\n\nRole: Keep git operations explicit, reviewable, and safe.\n\nBefore any git write, inspect and report working tree status, diff, and recent commits. Preserve unrelated user changes, stage only intended files, and stop on conflicts, detached HEAD, divergent branches, dirty base, untracked build artifacts, or unclear ownership.\n\nNever commit, amend, push, merge, rebase, reset, delete branches, delete worktrees, publish releases, or create PRs unless the human explicitly asks for that exact action.\n\nOutput: git state evidence, intended files, safety blockers, and the smallest safe decision needed from the human.\n\nBoundary: This is VGXNESS registry/context skill content only. It is not a provider-native OpenCode skill, must not be installed into .opencode, must not require skills.paths, and must not load remote content.",
+      "metadata": { "ownedBy": "vgxness", "kind": "registry-context-skill", "nativeProviderSkill": false, "category": "git" }
+    },
+    {
+      "name": "vgxness-pr-prep",
+      "description": "Prepares concise pull request evidence and reviewer-ready summaries.",
+      "version": "2026-06-16.v1",
+      "content": "# vgxness-pr-prep\n\nRole: Prepare a pull request only after the human explicitly asks for PR work.\n\nBefore opening a PR, inspect branch status, upstream tracking, base branch, recent commits, and diff against base. Summarize included commits, files changed, verification, rollout risk, reviewer burden, and any follow-ups.\n\nDo not push, publish, or create the PR without explicit human approval for that action. Prefer a focused PR over a broad mixed change.\n\nOutput: PR title/body draft or PR readiness report with evidence, risks, and reviewer notes.\n\nBoundary: This is VGXNESS registry/context skill content only. It is not a provider-native OpenCode skill, must not be installed into .opencode, must not require skills.paths, and must not load remote content.",
+      "metadata": { "ownedBy": "vgxness", "kind": "registry-context-skill", "nativeProviderSkill": false, "category": "pull-request" }
+    },
+    {
+      "name": "vgxness-stacked-prs",
+      "description": "Guides reviewable stacked PR slicing for dependent changes.",
+      "version": "2026-06-16.v1",
+      "content": "# vgxness-stacked-prs\n\nRole: Split dependent work into reviewable layers when one large PR would be hard to understand or risky to review.\n\nPrefer slices such as docs groundwork, tests/contracts, domain behavior, CLI/MCP surface, and follow-up polish. Keep each PR independently reviewable, explain dependencies, and avoid mixing unrelated fixes.\n\nDo not use stacked PRs for tiny fixes or emergency repairs unless the dependency structure is genuinely needed.\n\nOutput: proposed stack, branch/order guidance, reviewer burden tradeoffs, and cleanup notes.\n\nBoundary: This is VGXNESS registry/context skill content only. It is not a provider-native OpenCode skill, must not be installed into .opencode, must not require skills.paths, and must not load remote content.",
+      "metadata": { "ownedBy": "vgxness", "kind": "registry-context-skill", "nativeProviderSkill": false, "category": "pull-request" }
+    },
+    {
+      "name": "vgxness-strict-tdd",
+      "description": "Applies strict test-driven development for behavior-sensitive changes.",
+      "version": "2026-06-16.v1",
+      "content": "# vgxness-strict-tdd\n\nRole: Use strict TDD when changing behavior where regression risk matters.\n\nPreferred loop: write or identify a failing focused test, implement the smallest change, make the test pass, then refactor safely. Use especially for bug fixes, storage, permissions, workflow gates, MCP schemas, CLI contracts, and domain services.\n\nDo not force TDD ceremony onto docs-only, copy-only, or purely exploratory work. If a failing test cannot be created cheaply, explain why and choose focused verification instead.\n\nOutput: failing-test evidence when available, implementation notes, passing-test evidence, and residual risk.\n\nBoundary: This is VGXNESS registry/context skill content only. It is not a provider-native OpenCode skill, must not be installed into .opencode, must not require skills.paths, and must not load remote content.",
+      "metadata": { "ownedBy": "vgxness", "kind": "registry-context-skill", "nativeProviderSkill": false, "category": "testing" }
+    },
+    {
+      "name": "vgxness-review-size-guard",
+      "description": "Keeps implementation slices small enough to review safely.",
+      "version": "2026-06-16.v1",
+      "content": "# vgxness-review-size-guard\n\nRole: Protect reviewer attention and product safety by challenging oversized or mixed-scope changes.\n\nBefore large implementation, estimate affected subsystems, files, schema/storage changes, provider/setup impact, docs/tests, and verification cost. If the change is cross-cutting or hard to review, stop and recommend splitting into smaller slices.\n\nPrefer one coherent behavior change plus its tests/docs over unrelated bundles. For high-risk work, ask whether to reduce scope, split, or proceed as one larger change.\n\nOutput: review-size assessment, recommended slices, tradeoffs, and the next smallest safe step.\n\nBoundary: This is VGXNESS registry/context skill content only. It is not a provider-native OpenCode skill, must not be installed into .opencode, must not require skills.paths, and must not load remote content.",
+      "metadata": { "ownedBy": "vgxness", "kind": "registry-context-skill", "nativeProviderSkill": false, "category": "review" }
     }
   ],
   "attachments": [
@@ -76,6 +118,36 @@
     { "workflow": "sdd", "phase": "apply-progress", "skill": "vgxness-sdd-apply", "order": 100 },
     { "workflow": "sdd", "phase": "apply", "skill": "vgxness-sdd-apply", "order": 100 },
     { "workflow": "sdd", "phase": "verify", "skill": "vgxness-sdd-verify", "order": 100 },
-    { "workflow": "sdd", "phase": "archive", "skill": "vgxness-sdd-archive", "order": 100 }
+    { "workflow": "sdd", "phase": "archive", "skill": "vgxness-sdd-archive", "order": 100 },
+    { "workflow": "explore", "phase": "explore", "skill": "vgxness-workflow-selection", "order": 10 },
+    { "workflow": "debug", "phase": "diagnose", "skill": "vgxness-workflow-selection", "order": 10 },
+    { "workflow": "quickfix", "phase": "apply", "skill": "vgxness-workflow-selection", "order": 10 },
+    { "workflow": "plan", "phase": "plan", "skill": "vgxness-workflow-selection", "order": 10 },
+    { "workflow": "build", "phase": "apply", "skill": "vgxness-workflow-selection", "order": 10 },
+    { "workflow": "sdd", "phase": "manager", "skill": "vgxness-workflow-selection", "order": 10 },
+    { "workflow": "quickfix", "phase": "apply", "skill": "vgxness-git-safety", "order": 20 },
+    { "workflow": "build", "phase": "apply", "skill": "vgxness-git-safety", "order": 20 },
+    { "workflow": "sdd", "phase": "apply-progress", "skill": "vgxness-git-safety", "order": 20 },
+    { "workflow": "plan", "phase": "pr", "skill": "vgxness-git-safety", "order": 20 },
+    { "workflow": "plan", "phase": "pr", "skill": "vgxness-pr-prep", "order": 30 },
+    { "workflow": "plan", "phase": "stacked-prs", "skill": "vgxness-stacked-prs", "order": 30 },
+    { "workflow": "sdd", "phase": "tasks", "skill": "vgxness-stacked-prs", "order": 30 },
+    { "workflow": "quickfix", "phase": "apply", "skill": "vgxness-strict-tdd", "order": 40 },
+    { "workflow": "build", "phase": "apply", "skill": "vgxness-strict-tdd", "order": 40 },
+    { "workflow": "sdd", "phase": "apply-progress", "skill": "vgxness-strict-tdd", "order": 40 },
+    { "workflow": "plan", "phase": "plan", "skill": "vgxness-review-size-guard", "order": 50 },
+    { "workflow": "build", "phase": "apply", "skill": "vgxness-review-size-guard", "order": 50 },
+    { "workflow": "sdd", "phase": "tasks", "skill": "vgxness-review-size-guard", "order": 50 },
+    { "workflow": "sdd", "phase": "apply-progress", "skill": "vgxness-review-size-guard", "order": 50 },
+    { "targetType": "intent-signal", "targetKey": "workflow-selection", "skill": "vgxness-workflow-selection", "order": 10 },
+    { "targetType": "intent-signal", "targetKey": "git", "skill": "vgxness-git-safety", "order": 20 },
+    { "targetType": "intent-signal", "targetKey": "pull-request", "skill": "vgxness-git-safety", "order": 20 },
+    { "targetType": "intent-signal", "targetKey": "stacked-prs", "skill": "vgxness-git-safety", "order": 20 },
+    { "targetType": "intent-signal", "targetKey": "pull-request", "skill": "vgxness-pr-prep", "order": 30 },
+    { "targetType": "intent-signal", "targetKey": "stacked-prs", "skill": "vgxness-stacked-prs", "order": 30 },
+    { "targetType": "intent-signal", "targetKey": "tdd", "skill": "vgxness-strict-tdd", "order": 40 },
+    { "targetType": "intent-signal", "targetKey": "strict-tdd", "skill": "vgxness-strict-tdd", "order": 40 },
+    { "targetType": "intent-signal", "targetKey": "review-size", "skill": "vgxness-review-size-guard", "order": 50 },
+    { "targetType": "intent-signal", "targetKey": "broad-change", "skill": "vgxness-review-size-guard", "order": 50 }
   ]
 }