@mdferdousalam/agentic-sdlc 0.0.0-stage → 3.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,11 @@
+{
+  "name": "agentic-sdlc",
+  "owner": { "name": "Engr Md Ferdous Alam", "email": "mdferdousalam1989@yahoo.com", "url": "https://github.com/mdferdousalam" },
+  "plugins": [
+    {
+      "name": "agentic-sdlc",
+      "source": "./",
+      "description": "An enforced agent-based SDLC pipeline: specify, review, branch, implement, verify, review, gate, land, report — each stage owned by one agent and closed by a receipt a hook checks. Stack-agnostic; speaks OpenSpec or PRD/FRD."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,31 @@
+{
+  "name": "agentic-sdlc",
+  "version": "3.0.0",
+  "description": "An enforced agent-based SDLC pipeline that runs on any coding agent: specify, review, branch, implement, verify, review, gate, land, release. Each stage is owned by one agent and closed by a receipt bound to a commit. Claude Code, opencode, Codex and Cline refuse a skipped stage at the tool call; Gemini denies by policy; Cursor, Copilot, Windsurf and 20+ AGENTS.md hosts get the pipeline plus git-hook and CI enforcement. One adapter file per project; speaks OpenSpec or PRD/FRD.",
+  "keywords": [
+    "sdlc",
+    "pipeline",
+    "agents",
+    "openspec",
+    "code-review",
+    "quality-gate",
+    "spec-driven",
+    "hooks",
+    "governance",
+    "cursor",
+    "codex",
+    "gemini",
+    "copilot",
+    "cline",
+    "opencode",
+    "agents-md"
+  ],
+  "author": {
+    "name": "Engr Md Ferdous Alam",
+    "email": "mdferdousalam1989@yahoo.com",
+    "url": "https://github.com/mdferdousalam"
+  },
+  "homepage": "https://github.com/mdferdousalam/agentic-sdlc",
+  "repository": "https://github.com/mdferdousalam/agentic-sdlc",
+  "license": "MIT"
+}

package/CHANGELOG.md

@@ -0,0 +1,330 @@
+# Changelog
+
+All notable changes to this plugin. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and the versioning is [semantic](https://semver.org/).
+
+## [3.0.0] — 2026-10-25
+
+Findings become data, the gate can no longer be lowered to pass itself, and the six taxonomy
+domains the reviewers were silent on are covered.
+
+**Major, because the gate got stricter.** Nothing was removed and no configuration key
+changed meaning, but three things that previously passed now block: a configured
+`quality.cmd` actually runs, a diff that weakens the test suite is refused, and a budget
+ceiling stops a task. A repository that was green on 2.3.0 may not be green on this. That is
+the point, and it is a narrowing, so it is a major.
+
+### Added
+
+- **A finding contract.** `schema/finding.schema.json` and `sdlc finding write|list|show|close`.
+  A finding now carries an identity, a rule, a taxonomy address, evidence, a root cause, a
+  verification plan and a provenance — not just the word "blocking". Findings deduplicate by
+  content, so the same one raised twice is one finding rather than two comments.
+- **`docs/control-spec.md`**, normative for every agent: the four vocabularies, the repair
+  policy, the A–U and X1–X12 coverage map with an honest `review-level` marker, and a table of
+  56 rules. A rule that lives only in a prompt is that agent's opinion, and `sdlc finding
+  write` refuses a rule the table does not list.
+- **Severity and confidence as independent axes.** What an agent may repair unattended comes
+  from the pair, never from severity alone: `critical` at `low` confidence escalates to a
+  person, `high` at `medium` needs a reproduction first, and `advisory` is never committed at
+  any confidence.
+- **`sdlc baseline capture|compare|show`.** The branch-opener records what the verify command
+  said *before* any work began; the verifier and gate classify every later failure as `new`,
+  `pre-existing` or `fixed`. Comparison is over normalised signal lines, so it works in any
+  stack without a parser per test runner. Keyed to the merge base, so it survives commits —
+  unlike a receipt, which must not.
+- **`sdlc tests audit`.** Deleted test files, removed assertions, new skip markers, new
+  suppression directives and lowered thresholds. Every agent prompt already forbade these;
+  this is the part that does not negotiate. `--acknowledge` records a human decision and
+  deliberately does not waive the finding.
+- **`budget`.** `maxToolCalls` and `maxWallClockMin`, refused at the tool call and resettable
+  only by a person.
+- **`sdlc checkpoint write|resume|show`.** Stores a long task's progress *and the repository
+  state it assumed*; `resume` re-validates branch, commit ancestry, file digests and toolchain
+  before saying it is safe to continue.
+- **`concerns`**, a second profile axis beside `profile`. Six cross-cutting profiles —
+  `architecture`, `performance`, `memory`, `concurrency`, `data`, `platform` — covering
+  taxonomy domains B, E, F, G, J, K, N and S. A Go service wants `service` *and*
+  `concurrency`, which one field could not express. `sdlc init` proposes them from what the
+  repository actually contains and never imposes one.
+- **`sdlc-impact-analyst`** and **`sdlc-architecture-reviewer`**, both read-only. The first
+  reports dependents, published shapes and ordered migration steps *before* implementation;
+  the second walks the import graph, which is a different search from reading a diff.
+- **Environment fingerprint on every receipt**, so an environmental failure is distinguishable
+  from a defect.
+- **Metrics that measure outcomes**, not just activity: findings by severity and taxonomy
+  domain, verified repair rate, false-fix rate, human-intervention rate and reproducible
+  share.
+- Four evals for the new refusals, and tests for every detection in both directions.
+
+- **Publishing runs from a GitHub release, over OIDC.** `.github/workflows/publish.yml`
+  authenticates with npm Trusted Publishing — no stored token, no one-time password, and
+  provenance attached automatically. The trigger is a published release, so cutting one
+  stays the maintainer's act and the workflow is only the hands that carry it out; it
+  refuses if the tag and `package.json` disagree, and re-runs the gate rather than
+  trusting that it ran earlier.
+
+### Noted
+
+Running `sdlc tests audit` against this repository reported six weakenings that were not
+weakenings: its own detection patterns, its own test fixtures, and the eval that quotes a
+skipped test. A marker inside a string literal suppresses nothing and prose cannot disable a
+linter, so neither is excluded at the cost of a bypass — but six false positives on the
+tool's own diff is how a tool gets ignored, so both are now excluded, with regression tests
+in each direction. Found by dogfooding, which is the point of dogfooding.
+
+### Fixed
+
+- **`quality.cmd` never ran.** It was in the schema, documented as the Level 2 configuration,
+  and reserved as a receipt kind — and no agent or command executed it. The only consumer was
+  the generated CI workflow. The readiness gate and the mechanical gate now run it, and an
+  unset budget is reported as `skipped` rather than passed. Found by auditing this plugin
+  against its own design brief.
+- The OpenSpec commands in the agents and docs used `openspec change validate` and
+  `openspec change show`, which warn as deprecated on openspec 1.6. An agent reading our docs
+  would copy the deprecated form and paste the warning into its report as a finding. Found by
+  dogfooding: this repository now has the `openspec/` scaffolding its own config always said
+  it had.
+
+### Documented
+
+`docs/maturity.md` now says plainly what this still does not give you — detection precision
+and recall, runtime evidence, token accounting, sandboxing — and, for precision and recall,
+how to measure them yourself with a seeded-defect corpus. `docs/compliance.md` gains three
+more honest limits rather than three more claims.
+
+## [2.3.0] — 2026-10-25
+
+Published through every package manager a developer is likely to already have.
+
+### Added
+
+- **More ways in.** `packaging/build-pypi.sh` builds a PyPI distribution
+  (`agentic-sdlc-cli` — the unscoped `agentic-sdlc` is taken on PyPI too), staging the agents,
+  commands, docs and profiles into the wheel so the plugin root resolves the same way it does
+  from a checkout. `packaging/homebrew/agentic-sdlc.rb` is a tap-ready formula with the real
+  release checksum. `.codex-plugin/plugin.json` and `.agents/plugins/marketplace.json` make the
+  repository installable as a **Codex plugin**, and `gemini-extension.json` as a **Gemini
+  extension** — both straight from the git URL, no registry involved.
+- **`docs/install.md`** — all eight routes in one table, what each needs, and how to uninstall.
+
+### Verified
+
+The Codex plugin route was tested both ways, and the result is worth knowing: a plugin's hook
+is **not run until Codex has been asked to trust it**. Untrusted, only `Stop` fired and
+`git stash` went through; trusted, the same command was refused. `sdlc install codex` avoids
+the prompt because a hook in your own `~/.codex/hooks.json` is already your configuration —
+that path is verified working, receipt-dependent push gate included.
+
+The PyPI wheel was installed into a clean virtualenv and run. The Homebrew formula carries the
+real `v2.2.0` tarball checksum and is syntax-checked.
+
+### Fixed
+
+- The detected `secretScan` default used `gitleaks git … -n 50`, and gitleaks 8.x has no `-n`
+  shorthand on that subcommand — the gate's secret stage failed to run at all. It is now
+  `--log-opts="-n 50"`, with a regression test. Found by running this repository's own gate
+  against itself.
+
+## [2.2.0] — 2026-10-25
+
+A front door for everyone who is not using Claude Code. Until now the only one-command install
+was `/plugin install`; everybody else had to clone a repository and run a Python script. That,
+rather than any missing adapter, was what would have stopped other developers adopting this.
+
+### Added
+
+- **`install.sh`** — `curl -fsSL .../install.sh | sh`. Downloads a release into
+  `~/.agentic-sdlc`, links `sdlc` into a bin directory already on your PATH, and touches
+  nothing in your repository. No account, no sudo, no Python dependencies. It refuses to
+  proceed on Python older than 3.8 rather than failing later with something cryptic.
+- **npm package `@mdferdousalam/agentic-sdlc`** — `npx @mdferdousalam/agentic-sdlc install`.
+  Scoped because the unscoped name belongs to an unrelated project. The `bin` is a small Node
+  launcher rather than the Python file directly, so Windows gets a real shim instead of
+  depending on a shebang npm cannot honour there; it tries `python`, `py`, `python3` on Windows
+  and `python3`, `python` elsewhere, and says exactly what is missing if none works.
+
+### Verified
+
+Installing the packed npm
+tarball into a clean project and pushing: the generated `pre-push` hook
+refused an ungated push to `main`, and allowed it once a gate receipt existed. CI now checks
+the installer with `shellcheck`, that `package.json` and `plugin.json` agree on the version,
+and that the packed tarball's CLI actually runs.
+
+## [2.1.0] — 2026-10-25
+
+The pipeline stops being a Claude Code feature.
+
+### Added
+
+- **`sdlc install [targets…]`** — one generator, fifteen targets, from the same canonical
+  `agents/`, `commands/` and `docs/rules.md`. With no arguments it detects the agents on the
+  machine and installs for all of them. `--list` shows what is supported and what each host can
+  actually enforce; `--dry-run` writes nothing; `sdlc uninstall` removes only our blocks and the
+  files we own.
+- **Three more hosts that genuinely refuse a skipped stage**, not just instruct:
+  - **Codex CLI** — a `PreToolUse` entry merged into `~/.codex/hooks.json`, preserving every
+    other event already configured there. Codex uses the same hook wire contract as Claude Code.
+  - **Cline** — an executable `.clinerules/hooks/PreToolUse`, exit 2 blocks.
+  - **Gemini CLI** — no pre-tool hook exists, so the static refusals become
+    `.gemini/policies/agentic-sdlc.toml` rules (`decision = "deny"`), with the
+    receipt-dependent gates left to the git hooks. Commands ship as `.gemini/commands/sdlc/*.toml`.
+- **Instruction and command adapters** for Cursor (`.cursor/rules/*.mdc` with `alwaysApply`,
+  `.cursor/commands/`), GitHub Copilot (`copilot-instructions.md`, `.github/prompts/*.prompt.md`),
+  Windsurf, Roo, Kilo, Continue and Aider — plus `AGENTS.md` everywhere, which the agents.md
+  adopter list says is read by 20+ tools.
+- **Git hooks, installed by default** (`--no-git-hooks` to opt out). Every agent shells out to
+  git, so this is the only local enforcement that reaches Cursor, Copilot and a bare terminal
+  alike. An existing hook is appended to inside a marked block, never replaced.
+- **`sdlc install ci`** — a GitHub Actions gate that re-runs the verify command, secret scan and
+  quality budget where no agent can reach them. It does not read receipts; it re-does the work.
+- **`sdlc guard --command "<cmd>"`** — the same rules without a hook payload, which is how the
+  git hooks call it. Tested to agree with the stdin path rule for rule.
+- **`docs/platforms.md`** — the capability matrix, saying for each host whether it can refuse a
+  tool call, how the format was verified, and which three are only conventional and unverified.
+- **`sdlc doctor` is platform-aware** — which hosts are present, which are installed here, and
+  the exact command for each gap.
+
+### Changed
+
+- Everything written into a file we share with you is a marked block, so re-running updates only
+  our section and `uninstall` leaves your content. This applies to `AGENTS.md`, `GEMINI.md`,
+  `CONVENTIONS.md`, Copilot instructions, every rules file and both git hooks.
+- The hook command resolves `python3` or `python` at install time rather than assuming a
+  shebang works, which is a prerequisite for Windows.
+- `bin/sdlc-install-opencode` is **deprecated** — it now calls `sdlc install opencode`. Removal
+  in 3.0.0.
+
+### Verified
+
+Live, in real sessions:
+
+- **Codex CLI** — `git stash` refused, and `git push origin main` refused for want of a gate
+  receipt. The second one matters: it proves the *receipt-dependent* gates work on Codex, not
+  only the static pattern rules. The user's pre-existing `Stop` hook fired in the same session,
+  so the `hooks.json` merge is safe in practice and not just in the unit test.
+- **git hooks** — an ungated push to `main` refused from a plain terminal with no agent
+  involved; a feature branch allowed; `--no-verify` bypasses it exactly as documented.
+
+**Not verified:** the live refusal inside a Cline session, and the Cursor, Copilot and Roo
+pickup, which need interactive IDE sessions. Gemini could not be tested at all — Google now
+returns `UNSUPPORTED_CLIENT` for this client's free tier. Kilo, Windsurf and Continue use
+conventional paths that are not confirmed against a real tool; those adapters also write
+`AGENTS.md`, so the rules land either way. Windows remains untested.
+
+## [2.0.0] — 2026-10-25
+
+A rewrite. v0.1.0 was a document pipeline that asked a model to be careful; this is a pipeline
+whose stages cannot be skipped.
+
+### Added — lifecycle, governance and adoption
+
+Informed by a review of published agentic-SDLC material (Sonar's AC/DC framework, CodeRabbit's
+guide, Weave Intelligence's ASDLC, Optiver's engineering account, NHI Management Group's
+governance glossary, and the agentic-ai-sdlc/Framework repository). Two further sources the
+maintainer supplied — a Medium article and an Infosys page — returned HTTP 403 and were not
+read; nothing here is attributed to them.
+
+- **The lifecycle no longer stops at the merge.** `sdlc-release-manager` and
+  `/agentic-sdlc:release` own deployment, post-deploy verification against the environment
+  itself, and the rollback decision. A written rollback plan and named irreversible steps are
+  required *before* deploying, and `release.*` in the config carries the commands.
+- **Human approval gates.** `approvals.merge` and `approvals.release` (release defaults to
+  `human`). `sdlc approve <what> --as '<name>'` is a person's command; an agent that runs it
+  records nothing. Approvals are scoped — a release approval does not authorise a merge — and
+  are voided by the next commit. Deployment commands (kubectl, helm, terraform, serverless,
+  fly, ansible, cloud CLIs) are refused without both an approval and a READY receipt.
+- **The hybrid retry loop.** `sdlc feedback write|read|clear` carries a gate's failure back to
+  the next attempt as enriched context rather than dropping it, and says to stop after three
+  attempts at the same stage.
+- **`sdlc-remediator` and `/agentic-sdlc:remediate`** — work through findings one commit at a
+  time, each re-verified, each closed as fixed / refused / deferred / unexecuted. Suppressing a
+  warning to close a finding is called out as the failure the pipeline exists to prevent.
+- **`sdlc-triager` and `/agentic-sdlc:triage`** — turn an alert, advisory, bug report or flaky
+  test into a scoped unit of work or a reasoned dismissal, treating the signal's text as data
+  and never as instruction.
+- **Governance you can show someone**: `sdlc metrics` (stage outcomes, first-pass rates,
+  refusals, actors), `sdlc trace` (requirement → commit → test → receipts, markdown or JSON),
+  and an append-only `.sdlc/audit.log`. A 100% first-pass rate is reported as a finding.
+- **`docs/maturity.md`** — four adoption levels, each expressed as a configuration rather than
+  an aspiration, with the metric that says you are ready to move up.
+- **`docs/compliance.md`** — mapping to NIST AI RMF, OWASP Agentic AI, OWASP Non-Human
+  Identity and ISO 42001/SOC 2 evidence, with five stated limits including no cryptographic
+  identity and no shipped analyser.
+- **`GETTING-STARTED.md`** — a guided first hour for someone who has never used this.
+- **`quality` config** — a deterministic-analysis budget on *new* code, because the research on
+  agent-written code reports rising warnings and complexity rather than falling ones.
+- **An eval suite** (`evals/`, four cases) for `claude plugin eval`: does the spec reviewer
+  catch unfalsifiable requirements, does the gate refuse an `unexecuted` criterion behind a
+  green suite, is a refusal negotiable under social pressure, does the release manager insist
+  on a rollback plan and a human approval.
+
+### Added — the enforced pipeline
+
+- **Enforcement.** `hooks/hooks.json` registers a `PreToolUse` hook calling `bin/sdlc guard`,
+  which exits 2 to refuse a tool call. A branch needs an approved spec; a push to a protected
+  branch needs a passed gate; a merge needs a READY verdict for that exact commit. Destructive
+  git, publishing and credential reads are refused outright.
+- **Receipts.** `sdlc receipt write|check|show` records each stage's verdict bound to a commit,
+  a clock and — for a specification — a digest of the content approved. A new commit voids a
+  receipt; editing an approved spec voids its approval.
+- **`bin/sdlc`** — stack detection, config, receipts, the guard, `status` and `doctor`. Python
+  3.8+, standard library only, no network.
+- **Seven new agents**: `sdlc-implementer` (v0.1.0 had no agent that wrote code),
+  `sdlc-test-author`, `sdlc-code-reviewer`, `sdlc-security-reviewer`, `sdlc-verifier`,
+  `sdlc-lander`, `sdlc-reporter`.
+- **Eleven slash commands** — `:init`, `:feature`, `:implement`, `:verify`, `:review`,
+  `:gate`, `:readiness`, `:land`, `:report`, `:status`, `:doctor`.
+- **OpenSpec as a first-class engine.** `spec.engine` is detected; the spec reviewer runs
+  `openspec change validate --strict`, `tasks.md` becomes the acceptance criteria the verifier
+  and the gate check against, and the reporter archives the change after landing.
+- **Profiles** — `webapp`, `library`, `service`, `compiler`: opt-in standards a reviewer can
+  check, selected by `"profile"`.
+- **A JSON Schema** for the adapter, and a config that is re-detected without overwriting
+  anything set by hand.
+- **opencode support** — `bin/sdlc-install-opencode` installs the same agents, commands and
+  enforcement, calling the same guard.
+- **Tests** — 46 cases over detection, the guard, receipt binding and config overrides, run in
+  CI. The validator now checks agent/filename agreement, command→agent references, hook wiring
+  and that the CLI is executable.
+
+### Changed
+
+- **The evidence vocabulary is five words** — passed, failed, skipped, refused, unexecuted —
+  replacing `met/partial/missing` and `pass/fail`. A test that did not run is `unexecuted`, and
+  the gate treats it as such.
+- **Specifications are no longer hand-versioned.** `PRD_v1.0.md` and `CVR_of-DI-v1.0_r1.md`
+  become `PRD.md` and `verification.md`; git keeps the history.
+- `sdlc.config.json` gains `spec`, `secretScan`, `profile`, `receipts`, `enforce`, `heavy`, and
+  a `version` field.
+- Every agent now reads `docs/rules.md` rather than restating the rules, so they cannot drift
+  apart.
+
+### Removed
+
+- **The configurability audit from the core.** "No hardcoded value the spec marked
+  configurable", reference tables, admin CRUD surfaces and 3NF were rules from the application
+  the kit was extracted from, and they produced noise on every other kind of project. They now
+  live in `profiles/webapp.md` and apply when you ask for them.
+- **The DI stage.** A third document between the FRD and the code mostly restated the FRD; the
+  implementer reads the specification directly. What the DI uniquely carried — the decisions
+  taken while building — is now in the implementation report, where it is written after the
+  fact and is therefore true.
+- The `sdlc-init`, `start-feature`, `dev-instructions`, `verification-report` and
+  `implementation-report` skills, replaced by commands and agents. Three reference skills
+  remain: `agentic-sdlc-pipeline`, `openspec-with-sdlc`, `writing-specifications`.
+
+### Migration from 0.1.x
+
+1. `/agentic-sdlc:init --write` — rewrites `sdlc.config.json` in the v2 shape, keeping your
+   `trunk`, `verifyCmd` and anything else you had set.
+2. Add `.sdlc/` to `.gitignore`.
+3. Set `"profile": "webapp"` if you relied on the configurability and data-model rules.
+4. Existing `PRD_v1.0.md` / `FRD_v1.0.md` still read fine; new specs drop the version suffix.
+5. `/agentic-sdlc:doctor`.
+
+## [0.1.0] — 2026-10
+
+First release: PRD → FRD → branch → DI → code → CVR → readiness gate → IR, four agents, five
+skills, and a detected `sdlc.config.json`.

package/GETTING-STARTED.md

@@ -0,0 +1,174 @@
+# Getting started
+
+A guided first hour. No prior knowledge of the pipeline assumed. If you have ten minutes, do
+Part 1 and stop — it is useful on its own.
+
+## What this actually is, in one paragraph
+
+You ask an AI agent to build something. It writes code fast, and the hard part becomes knowing
+whether the result is any good. This plugin puts stages between "asked" and "merged" — write
+the spec, review the spec, branch, build, verify, review, gate, land — and then makes those
+stages impossible to skip, by refusing the tool call. You still decide everything that matters.
+The pipeline stops a confident agent from quietly skipping the step that would have caught it.
+
+## Part 1 — install and look around (10 minutes)
+
+**Using Claude Code?**
+
+```sh
+/plugin marketplace add mdferdousalam/agentic-sdlc
+/plugin install agentic-sdlc
+```
+
+**Using anything else** — Cursor, Codex, Copilot, Gemini, Cline, Windsurf, Zed, Aider:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/mdferdousalam/agentic-sdlc/main/install.sh | sh
+sdlc install        # detects your agents and sets each one up
+```
+
+Or with npm, if that is more your habit: `npx @mdferdousalam/agentic-sdlc install`.
+Either way you need `git` and Python 3.8 or newer — nothing else.
+
+It installs git hooks too, because on most hosts that is the only thing that can actually stop
+a mistake. [What each host can and cannot enforce](docs/platforms.md) — worth two minutes
+before you trust it.
+
+Then, inside a project you work on:
+
+```text
+/agentic-sdlc:init --write
+/agentic-sdlc:doctor
+```
+
+`init` looks at your repository and writes `sdlc.config.json` — your package manager, your
+trunk branch, your test runner, your verify command. **Open that file and read it.** It is the
+only place the pipeline learns about your project, and detection guesses. The field that
+matters most is `verifyCmd`: the command that tells you the code is sound. If it is wrong or
+empty, fix it now; nothing downstream works without it.
+
+`doctor` tells you what is missing. `gitleaks not found` is worth fixing (`brew install
+gitleaks`); the rest you can leave.
+
+### See the enforcement for yourself
+
+Ask your agent to run `git stash`. It will come back refused. That is the point: the rules are
+not advice to a model that may or may not follow them.
+
+## Part 2 — one real feature (30–45 minutes)
+
+Pick something small and genuinely useful. Not a toy, not a rewrite.
+
+### 1. Say what you want
+
+```text
+/agentic-sdlc:feature "add a --format=json flag to the export command"
+```
+
+Three things happen. A spec gets written. A second agent reviews it and usually asks for
+changes — **this is the pipeline working, not failing**. Then, only once the spec is approved,
+a branch is created.
+
+> **Read the spec before it is approved.** Five minutes here saves an hour later. You are
+> looking for: would someone who knows nothing else build the right thing from this? Is every
+> requirement something you could check? Is anything missing that you were assuming?
+
+### 2. Let it build
+
+```text
+/agentic-sdlc:implement
+```
+
+It works the checklist in order, writes tests, commits each item. If the spec turns out to be
+ambiguous, it stops and asks rather than guessing. When that happens, answer the question and
+let it carry on — that stop just prevented a silent wrong decision.
+
+### 3. Check what was built against what you asked for
+
+```text
+/agentic-sdlc:verify
+/agentic-sdlc:review
+```
+
+`verify` goes requirement by requirement and finds the code and the test for each. `review`
+reads the diff for defects and, where it matters, security.
+
+You will probably see `unexecuted` next to a requirement. It means nobody ran a test for it.
+It is not a failure and it is not a pass, and the gate will treat it as blocking. That one word
+is most of the value here.
+
+### 4. The gate
+
+```text
+/agentic-sdlc:readiness
+```
+
+Clean tree, your verify command, a secret scan, the reviewers, every criterion checked against
+real evidence. It answers READY or NOT-READY.
+
+**NOT-READY on your first run is normal.** Fix what it found — `/agentic-sdlc:remediate` works
+through findings one at a time — and run it again.
+
+### 5. Land it
+
+```text
+/agentic-sdlc:land
+```
+
+Branch pushed, pull request opened, with the criteria and their evidence in the body. Review
+the PR yourself and merge it the way you always do.
+
+## When something is blocked
+
+You will see a message like:
+
+```text
+BLOCKED by agentic-sdlc: merging needs a READY readiness receipt, and there is no readiness
+receipt. Run `/agentic-sdlc:readiness`.
+```
+
+Every refusal names what is missing and what to do. Three rules:
+
+1. **Do the thing it asks for.** It is almost always two minutes of work.
+2. **Do not argue with the agent about it.** The refusal is a hook, not an opinion; the model
+   cannot grant an exception and will waste your tokens trying.
+3. **If a rule is genuinely wrong for your project, turn it off in the config** — `enforce` in
+   `sdlc.config.json`. That is a visible, reviewable decision. Working around it is not.
+
+`/agentic-sdlc:status` shows which stages have left evidence and which have not.
+
+## The vocabulary, because it is used precisely
+
+**passed** — it ran and succeeded. **failed** — it ran and did not.
+**skipped** — the runner skipped it. **refused** — the system correctly declined.
+**unexecuted** — nobody ran it.
+
+The last three are not "passed". Most bad agentic reporting comes from collapsing them.
+
+## Three things worth doing in week one
+
+1. **Set a profile.** `"profile": "webapp"`, `library`, `service` or `compiler` in the config.
+   The reviewers then hold you to the standards that match what you are building, instead of
+   generic advice. See [profiles](profiles/README.md).
+2. **Make `verifyCmd` strict.** It is the floor of every gate. If it does not catch a broken
+   build today, it will not catch one next month either.
+3. **Read one spec properly before approving it.** The single highest-leverage habit here. An
+   agent will build the wrong thing beautifully if you let it.
+
+## Common questions
+
+**Do I have to use every stage?** No. The three enforced ones are branch-needs-approved-spec,
+push-to-trunk-needs-gate, and merge-needs-readiness, and each can be turned off in `enforce`.
+Start with whichever subset you will actually use.
+
+**Does this work without OpenSpec?** Yes — the spec becomes a PRD and an FRD, and everything
+downstream is identical. OpenSpec adds a validator and an archive if you want them.
+
+**Does it work outside Claude Code?** Yes — `sdlc install` covers Codex, Cline, Cursor, Copilot, Gemini, Windsurf, Roo, Kilo, Continue, Aider and every AGENTS.md host. Four of them can refuse a tool call outright; the rest rely on the git hooks and CI. The [matrix](docs/platforms.md) is explicit about which is which.
+
+**What if my team does not use agents yet?** The gates work on human changes too, and most
+teams find the specification review is where the value shows up first.
+
+**Where do I go next?** [The pipeline in detail](docs/pipeline.md) ·
+[Configuration](docs/configuration.md) · [Maturity levels](docs/maturity.md) ·
+[A worked example](examples/worked-example.md)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Engr Md Ferdous Alam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.