@mdferdousalam/agentic-sdlc 0.0.0-stage → 3.0.0

package/schema/sdlc.config.schema.json

@@ -0,0 +1,324 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mdferdousalam/agentic-sdlc/schema/sdlc.config.schema.json",
+  "title": "agentic-sdlc project adapter",
+  "description": "The only file in a project that knows its stack. Every agent reads it; none hardcodes a package manager, a branch name or a test runner.",
+  "type": "object",
+  "required": [
+    "trunk",
+    "spec"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "const": 2,
+      "description": "Adapter format version."
+    },
+    "trunk": {
+      "type": "string",
+      "description": "The branch work merges into.",
+      "examples": [
+        "main",
+        "master",
+        "develop"
+      ]
+    },
+    "stack": {
+      "type": "string",
+      "description": "Detected language or ecosystem; informational."
+    },
+    "pm": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Package manager or build driver."
+    },
+    "monorepo": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "enum": [
+        "turbo",
+        "nx",
+        "lerna",
+        "workspaces",
+        null
+      ]
+    },
+    "commits": {
+      "enum": [
+        "conventional",
+        "descriptive"
+      ],
+      "description": "Commit message style the lander and implementer follow."
+    },
+    "test": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "Test runners by kind, e.g. {\"unit\":\"vitest\",\"e2e\":\"playwright\"}."
+    },
+    "spec": {
+      "type": "object",
+      "required": [
+        "engine"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "engine": {
+          "enum": [
+            "openspec",
+            "prd-frd"
+          ],
+          "description": "openspec: proposal/design/tasks + delta specs, validated by the openspec CLI. prd-frd: a PRD and an FRD with numbered requirements."
+        },
+        "docsRoot": {
+          "type": "string",
+          "description": "Where specifications live."
+        },
+        "strict": {
+          "type": "boolean",
+          "description": "openspec: validate with --strict."
+        }
+      }
+    },
+    "branchScheme": {
+      "type": "string",
+      "description": "Placeholders are filled from the unit of work, e.g. {kind}/{slug}."
+    },
+    "verifyCmd": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "The mechanical check: lint, types, tests. Without it nothing can be gated."
+    },
+    "gateCmd": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "A heavier project-specific gate, run instead of verifyCmd when set."
+    },
+    "secretScan": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "A command that fails when a credential appears in the branch's commits."
+    },
+    "heavy": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Prose rule for workloads that must be bounded or serialised."
+    },
+    "profile": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "The kind of project this is: an opt-in standards profile from the plugin's profiles/ directory (webapp, library, service, compiler). One per project."
+    },
+    "concerns": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Cross-cutting standards from profiles/concerns/, applied in addition to the project-kind profile. A Go service needs service AND concurrency, so this is a list rather than a second single choice. Known: architecture, performance, memory, concurrency, data, platform.",
+      "examples": [
+        [
+          "concurrency",
+          "performance"
+        ]
+      ]
+    },
+    "reviewers": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Agents the readiness gate fans out to."
+    },
+    "protected": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Branches a push may not reach without a passed gate receipt. Globs allowed."
+    },
+    "receipts": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "maxAgeMin": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "How long a receipt stays valid."
+        }
+      }
+    },
+    "enforce": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "What the PreToolUse hook refuses. Turning one off is a deliberate, recorded choice.",
+      "properties": {
+        "pushToTrunkNeedsGate": {
+          "type": "boolean"
+        },
+        "mergeNeedsReadiness": {
+          "type": "boolean"
+        },
+        "branchNeedsApprovedSpec": {
+          "type": "boolean"
+        },
+        "blockDestructiveGit": {
+          "type": "boolean"
+        },
+        "blockPublishing": {
+          "type": "boolean"
+        },
+        "blockCredentialReads": {
+          "type": "boolean"
+        }
+      }
+    },
+    "neverByAgent": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Actions reserved to a human, stated for the agents to read."
+    },
+    "quality": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Deterministic analysis budget on NEW code. Peer-reviewed work on repositories that adopted coding agents reports persistent rises in analysis warnings and complexity, so the budget is on what a change adds, not on the whole repository.",
+      "properties": {
+        "cmd": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Static analysis / coverage command; non-zero exit fails the gate."
+        },
+        "coverageNewPct": {
+          "type": [
+            "number",
+            "null"
+          ],
+          "minimum": 0,
+          "maximum": 100,
+          "description": "Minimum coverage required on changed lines."
+        }
+      }
+    },
+    "release": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "How a merged change reaches users. Merging is not shipping; this is the distance between them.",
+      "properties": {
+        "deployCmd": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "smokeCmd": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Proves the change works in the environment it was deployed to, not in CI."
+        },
+        "rollbackCmd": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The written way back. A deployment without one is not ready."
+        },
+        "environments": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Lowest first. Production is never deployed before the environment below it has been observed."
+        }
+      }
+    },
+    "approvals": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Which actions need a named human. An agent can never satisfy a 'human' approval: it records who is accountable, and an agent approving its own work records nothing.",
+      "properties": {
+        "merge": {
+          "enum": [
+            "agent",
+            "human"
+          ]
+        },
+        "release": {
+          "enum": [
+            "agent",
+            "human"
+          ]
+        }
+      }
+    },
+    "attributeCommits": {
+      "type": "boolean",
+      "description": "Add an agent identity trailer to commits, so a change can be traced to the actor that made it."
+    },
+    "budget": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Ceilings an agent cannot raise for itself. An agent that cannot stop is a cost centre with a git token. The tool cannot see the host's token meter, so it counts what it can observe: tool calls through the hook, wall-clock since the task began, and repair attempts.",
+      "properties": {
+        "maxToolCalls": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Tool calls per task before the hook refuses. 0 means no ceiling, which means nothing will stop a runaway task."
+        },
+        "maxWallClockMin": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Minutes per task before the hook refuses. 0 means no ceiling."
+        },
+        "maxRetries": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Attempts at one stage before the pipeline says to stop and report. Default 3: past that, the specification is usually the problem, not the code."
+        },
+        "stopPolicy": {
+          "enum": [
+            "refuse",
+            "warn"
+          ],
+          "description": "refuse: the hook blocks. warn: it says so and allows it. refuse is the point."
+        }
+      }
+    },
+    "suiteAudit": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Controls for `sdlc tests audit`. Exemption is declared here rather than inferred from a line's text, because anything decided from the text can be rewritten by the actor the control exists to constrain. Adding a glob is itself reported as a weakening, so the escape hatch cannot be used quietly.",
+      "properties": {
+        "exclude": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Paths or globs exempt from the suppression-marker half of the audit. Deleted tests, removed assertions and lowered thresholds still fire on them. For files that genuinely DEFINE these patterns \u2014 a detector, its fixtures, an adversarial eval prompt \u2014 not for files that merely trip it."
+        }
+      }
+    }
+  }
+}

package/skills/agentic-sdlc-pipeline/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: agentic-sdlc-pipeline
+description: >
+  The agent-based SDLC pipeline: how to take a unit of work from request to merged, which agent
+  owns each stage, and which receipt each stage leaves. Use when asked to set up, explain, run
+  or debug the SDLC pipeline, when a user says "use the pipeline / follow SDLC", or when
+  deciding which /agentic-sdlc command comes next.
+---
+
+# The pipeline
+
+Read `${CLAUDE_PLUGIN_ROOT}/docs/rules.md` before running any stage. Read the project's
+`sdlc.config.json` to learn its stack — never assume one.
+
+| # | Stage | Command | Owner | Leaves |
+| --- | --- | --- | --- | --- |
+| 0 | Adapt | `/agentic-sdlc:init` | — | `sdlc.config.json` |
+| 1 | Specify | `/agentic-sdlc:feature` | `sdlc-spec-writer` | a specification |
+| 2 | Review the spec | ↑ same command | `sdlc-spec-reviewer` | `spec` receipt |
+| 3 | Branch | ↑ same command | `sdlc-branch-opener` | a branch |
+| 3b | Impact | `/agentic-sdlc:impact` | `sdlc-impact-analyst` | who depends on this, and in what order |
+| 4 | Implement | `/agentic-sdlc:implement` | `sdlc-implementer` | code and tests |
+| 5 | Verify | `/agentic-sdlc:verify` | `sdlc-verifier` | `verification` receipt |
+| 6 | Review | `/agentic-sdlc:review` | `sdlc-code-reviewer`, `sdlc-security-reviewer` | `review`, `security` receipts |
+| 7a | Mechanical gate | `/agentic-sdlc:gate` | — | `gate` receipt |
+| 7b | Readiness | `/agentic-sdlc:readiness` | `sdlc-readiness-gate` | `readiness` receipt |
+| 8 | Land | `/agentic-sdlc:land` | `sdlc-lander` | branch pushed, pull request |
+| 9 | Report | `/agentic-sdlc:report` | `sdlc-reporter` | implementation report, docs |
+| 10 | Release | `/agentic-sdlc:release` | `sdlc-release-manager` | `postdeploy` receipt, or a rollback |
+| — | Triage | `/agentic-sdlc:triage` | `sdlc-triager` | a scoped unit of work, or a reasoned dismissal |
+| — | Remediate | `/agentic-sdlc:remediate` | `sdlc-remediator` | one commit per finding, re-verified |
+
+The branch stage also captures a **baseline** — what the verify command said before any work
+began. Every later failure is then attributable: new, pre-existing, or fixed. Without it an
+agent spends its retries on a test that was already red.
+
+`/agentic-sdlc:status` says which receipts hold right now; `/agentic-sdlc:doctor` checks the
+install and the configuration.
+
+## What makes it different from a checklist
+
+Three stages are enforced by a `PreToolUse` hook, not by instruction:
+
+- a branch needs an **approved spec** receipt whose digest still matches the specification;
+- a push to a protected branch needs a **passed gate** receipt for that exact commit;
+- a merge needs a **READY readiness** receipt for that exact commit, plus a human
+  `approval_merge` where the project asks for one;
+- a deployment needs a human `approval_release` **and** a READY receipt — an agent cannot
+  approve its own release.
+
+A new commit voids a receipt. Editing an approved specification voids its approval. The hook
+also refuses destructive git, publishing and credential reads. None of this makes a dishonest
+verdict honest; it makes a skipped stage impossible.
+
+## Starting in an existing repository
+
+1. `/agentic-sdlc:init --write`, then read the config and correct it. `verifyCmd` must be real.
+2. Choose a profile if one fits (`${CLAUDE_PLUGIN_ROOT}/profiles/`); "none" is fine.
+3. `/agentic-sdlc:doctor` until it is clean.
+4. `/agentic-sdlc:feature "<what you want>"`.
+
+## When a stage says no
+
+That is the pipeline working. Fix the cause, re-run the stage, and let it write a new receipt.
+Never edit a receipt, and never route around the hook — if the route is blocked, the route is
+wrong.

package/skills/openspec-with-sdlc/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: openspec-with-sdlc
+description: >
+  How the SDLC pipeline uses OpenSpec as its specification engine — creating a change,
+  validating it, turning tasks.md into acceptance criteria, and archiving after landing. Use
+  when a repo has openspec/ or spec.engine is "openspec", or when asked how OpenSpec and the
+  pipeline fit together.
+---
+
+# OpenSpec as the pipeline's spec engine
+
+When `spec.engine` is `openspec`, the specification is an OpenSpec change rather than a PRD and
+an FRD. The pipeline gains three things from it: a layout other tools understand, a validator
+that fails on a malformed spec, and an archive step that keeps "what is proposed" honest.
+
+## The mapping
+
+| Pipeline idea | OpenSpec artefact |
+| --- | --- |
+| Why this work exists | `openspec/changes/<id>/proposal.md` |
+| What was chosen, and over what | `<id>/design.md` |
+| The acceptance criteria | `<id>/tasks.md` — one checklist item per deliverable |
+| Requirements on a published capability | `<id>/specs/<capability>/spec.md` |
+| The spec is well-formed | `openspec validate <id> --strict` |
+| The work is done | every `tasks.md` item ticked, in the commit that did it |
+| The change is history | `openspec archive <id>` |
+
+## The commands that matter
+
+```sh
+openspec list                              # active changes — check before proposing
+openspec list --specs                      # published capabilities
+openspec show <id>                  # read one
+openspec validate <id> --strict     # the spec reviewer runs this first
+openspec archive <id>                      # the reporter runs this after landing
+```
+
+`openspec validate --strict --json` is machine-readable: a failure is an automatic
+`changes-requested` and the reviewer quotes it rather than paraphrasing.
+
+## Writing tasks.md so the rest of the pipeline works
+
+`tasks.md` is not a to-do list; it is the acceptance criteria the verifier and the readiness
+gate check against. Each item must name **one deliverable with an observable outcome**. "Wire up
+the parser" cannot be verified. "`parse()` refuses an unterminated string with error `E0012`,
+with a test" can.
+
+The implementer ticks each item in the same commit as the work; the verifier maps each item to
+`file:line` plus a test outcome; the readiness gate treats an unticked finished item as
+sloppiness and a ticked unfinished item as a blocker.
+
+## Archiving
+
+Archive only after the change has landed and its delta specs are reflected in the published
+ones. `openspec list` should show what is genuinely in flight — a finished change left active
+is a lie the next session will believe.

package/skills/writing-specifications/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: writing-specifications
+description: >
+  How to write a specification this pipeline can verify — falsifiable requirements, specified
+  refusals, stated scope, named open questions. Use when writing or reviewing a PRD, FRD,
+  OpenSpec proposal or tasks list, or when a spec review returns changes-requested.
+---
+
+# A specification the pipeline can verify
+
+The test of a specification here is mechanical: can the verifier, months later, take each line
+and find evidence for or against it? If not, the line is prose, not a requirement.
+
+## Falsifiable, one deliverable at a time
+
+For each requirement, name the observation that would show it unmet.
+
+| Not verifiable | Verifiable |
+| --- | --- |
+| Improve error handling | On a 5xx from the payment provider, the order stays `pending`, the user sees `PAY-003`, and the job retries three times at 1s/4s/16s |
+| Make the parser robust | `parse()` refuses an unterminated string with `E0012`, naming the line and column |
+| Add caching | A second identical request within 60s is served from cache, and a write invalidates it within one request |
+
+## Specify the refusals
+
+Most defects live where nothing was specified: the empty input, the duplicate, the expired
+token, the concurrent write, the half-finished upload. Every error a user can reach has a name,
+a code where the project uses codes, and a stated message. "The implementation will decide" is
+how two call sites end up disagreeing.
+
+## State the scope, both ways
+
+Write what is **out** of scope as deliberately as what is in. An explicit non-goal stops the
+implementer gold-plating and stops the reviewer raising it as a gap.
+
+## Name the open questions
+
+An unknown written down is a question; an unknown assumed is a defect with a delay. Mark the
+ones that are the maintainer's — publishing, a safety rule, removing something users have,
+licensing, scope — and leave them open rather than deciding them.
+
+## Cite, do not restate
+
+If an authority document already defines something, cite the section. A restatement is a second
+copy that will drift, and the drift will be discovered by someone trusting the wrong one.
+
+## Size
+
+One unit of work is one branch, one review and one merge. If the checklist has twenty items
+spanning three subsystems, it is three units wearing one name — split it, and say what order
+they go in.