v3.2.0: conventions gate, config dogfooding, Agent Plugins manifest

Sharpens the red-team gate and hardens the repo's own conventions, validated by a defect-injection eval (11 arms: A/B on planted and clean diffs, plus a self-application arm), two independent release reviews, and a run of the real devloop:red-team against the release diff. The eval also refuted two candidate additions (an external-compat angle and blindspot-probe handling): the shipped gate already caught those defect classes, so neither shipped.

Added

• Landing site under docs/. A GitHub Pages site (index.html, llms.txt, FAQ). Shipped after 3.1.1 and carried in this release.
• devloop dogfoods its own config convention. The README tells users to commit .devloop/config.md and domain.md, but the repo gitignored the whole directory, so red-team's conventions angle returned nothing on every self-review it had ever run. Both are now committed, alongside a thin harness-native AGENTS.md that points at them. config.md's Standards carry only rules validate.sh cannot mechanize, each traceable to the release that fixed it.
• Vendor-neutral Agent Plugins manifest. A root plugin.json in the Agent Plugins 1.0.0 format (backed by Amazon, Cursor, Microsoft, OpenAI, and Vercel; Kiro has announced support), alongside the existing Claude Code and Codex manifests. skills/ was already conformant. Claude Code and Codex read their own manifests and ignore the root one (verified with claude plugin validate --strict); conformance is validated against the published JSON Schema, not a tested install.
• validate.sh sections 19 to 21. Section 19 guards the dogfooded config; section 20 pins the red-team angle counts across the README, docs, SKILL.md, and the mode table; section 21 validates the new manifest and pins version and description across all three manifests. The suite is now 244 checks, up from 219.

Changed

• Convention faults now block the gate. The Phase 4 verdict ladder FAILs on a CONFIRMED conventions finding whose failure scenario is a genuine fault (security, data loss, a broken documented invariant, or a robustness gap such as a missing rate limit or an unbounded query); purely stylistic findings (naming, commit-message format, doc location) stay WARN. Previously only CONFIRMED correctness could FAIL, so a real standards violation with no correctness face could pass the /implement gate. The gate wording and the README/docs match.
• No fixed cap on findings. Removed the numeric per-angle limits in red-team in favor of "surface every candidate with a nameable failure"; the no-pad discipline is unchanged.

v3.1.1: doc and consistency fixes

Documentation and consistency fixes surfaced by two independent release-readiness reviews. No behavior change from 3.1.0: the loop, gates, and schemas are identical.

Fixed

• Examples are concrete, not templates. The README described examples/<stack>/ files as YOUR_*_HERE placeholder templates; they are concrete, stack-specific instances. Reworded to "copy the closest to .devloop/ and adapt it."
• Examples surface the directory settings. Each examples/*/config.md now shows the spec-directory / tracker-directory settings (defaults docs/specs/ and .devloop/trackers/).
• Accurate config cross-references. quality-checklist.md cites the real config headings (§Standards to Verify, §Blindspots to Check); examples/*/domain.md attributes Domain-Specific Concerns to the Clarification Taxonomy (§9); chunk-template.md's state-holder pointer now resolves to implement SKILL.md §2.2.
• /implement Process Overview now states a passing plan_review is PASS or PASS-WITH-WARNINGS.
• Marketplace descriptions de-drifted to match plugin.json verbatim per harness.
• validate.sh housekeeping: dash guard now also scans the examples/ configs; a stale evals/ comment was removed.

v3.1.0: .devloop/ project-config convention

3.1.0

A single project-local home for devloop's per-project files: .devloop/.
This fixes config discovery under a plugin install (where the skills live
in a read-only shared cache and a PROJECT.md beside SKILL.md never
resolves in the user's project) and gives trackers a stable home outside
docs/.

Added

• .devloop/ convention: skills and agents read project config from
  .devloop/ in the project root:
  • config.md, engineering config (build/test/lint commands, architecture
    rules, standards, blindspots, commit conventions, and the spec/tracker
    directory settings), read by /plan, /implement, review-plan,
    review-impl, red-team, and /spec (for the spec-directory setting).
  • domain.md, pure domain knowledge (domain context, architecture
    overview, domain-specific concerns, existing patterns, quality
    standards), read by /spec.
  • trackers/, home for impl-tracker-<feature>.json, written by /plan.
• Config discovery: each skill and agent resolves config as
  .devloop/<file> in the project, else generic mode. This is why a plugin
  install now works: the read-only cache holds the skills, but they read
  .devloop/ from the project. There is no copied-in PROJECT.md fallback
  (the old template files are removed); .devloop/ is the only
  project-config source.
• validate.sh section 17: fails if a core file reintroduces the
  plugin-cache config pointer ("plugin's skill directory") and requires each
  skill and review agent to name the .devloop/ home.
• validate.sh section 16 now also rejects en dashes (not just em
  dashes), closing a gap in the standard-punctuation guard.
• Plugin marketplaces: .claude-plugin/marketplace.json (Claude Code)
  and .agents/plugins/marketplace.json (Codex, its native catalog
  location) so devloop installs via
  /plugin marketplace add KashZod/devloop then
  /plugin install devloop@kashzod, and the codex plugin marketplace add
  / codex plugin add equivalents.

Changed

• Config ownership: config.md owns the operational paths (spec
  directory, tracker directory) alongside the engineering settings;
  domain.md is now purely domain knowledge. Commit conventions live only
  in config.md (read by the skills that commit). /spec reads its output
  path from config.md and its domain context from domain.md.
• Tracker home: /plan writes trackers to .devloop/trackers/ by
  default (was docs/); /implement, review-plan, and review-impl
  look there.
• Example configs live in one place per stack under a top-level
  examples/<stack>/ (typescript-node, python, rust,
  android-kotlin), each holding a config.md and a domain.md; copy the
  closest directory to .devloop/. This replaces the split
  skills/spec/project-configs/ (domain) and
  skills/implement/project-configs/ (engineering) layout, and
  validate.sh now checks the examples in a single section (the former
  duplicate example-config check is removed).
• /implement Phase 3 sizes the red-team half by diff size, the
  same way /plan sizes work (its Trivial / Small / Medium+ / Large
  table). A single-file change (or a trivial one with no new logic) runs
  one red-team in mode: both, unchanged from before. A broader,
  multi-file or cross-cutting diff (/plan Medium+ and Large) splits the
  red-team half into parallel mode: bugs and mode: cleanup runs so
  neither family crowds the other out. review-impl runs alongside in
  every case. Because red-team in mode: cleanup can apply fixes, the
  split invokes the cleanup run report-only, so all three concurrent
  agents only report and the parallel gate stays read-only. No new
  red-team mode was added; report-only is an invocation instruction
  inside cleanup mode.
• validate.sh section 18 asserts the Phase 3 spawn stays
  size-adaptive (it names the mode: both, mode: bugs, mode: cleanup,
  and report-only markers), so a future edit can't silently revert to
  the fixed single-agent gate.

Migration

• Move in-flight trackers. Trackers previously written under docs/
  now live in .devloop/trackers/, and this release drops the docs/
  read-fallback. Move any existing docs/impl-tracker-*.json into
  .devloop/trackers/, or pass an explicit tracker path when invoking
  /implement or the review agents.
• Migrate an old PROJECT.md. The copied-in PROJECT.md fallback is
  gone; .devloop/ is the only project-config source. Split any old
  PROJECT.md into .devloop/config.md (engineering settings and paths)
  and .devloop/domain.md (domain knowledge), or copy the closest
  examples/<stack>/ directory as a starting point.

Fixed

• Valid Claude Code manifest. .claude-plugin/plugin.json no longer
  enumerates skills/agents as arrays of objects, a shape the current
  schema rejects (claude plugin validate reported skills: Invalid input
  / agents: Invalid input). Claude Code auto-discovers skills/ and
  agents/, so the keys are dropped; the manifest now passes
  claude plugin validate --strict. The Claude manifest also gains
  repository and license, matching the Codex manifest.

v3.0.0

3.0.0

Three-command split, a harness-agnostic rewrite, and a de-overlapped
review layer. The loop is now /spec -> /plan -> /implement, mapping to
three gates (spec validation, plan review, code review) one gate per
command, with a convergence back-edge where /implement re-runs the
plan-review gate in-session. This release rolls up every change since
2.5.0. Breaking change: /implement no longer plans.

Added

• /plan skill: decomposes a spec into an ordered, dependency-aware
  chunk plan, writes the JSON tracker, and runs the review-plan gate
  before any code is written. This is the old /implement Phases 1-2.5
  (analysis, chunk decomposition, dependency graph, tracker creation,
  plan-review gate), promoted from a buried mid-/implement checkpoint to
  a first-class command. The plan-review gate is the most important
  checkpoint in the loop, now its own visible step.
• Convergence back-edge: when a code-time finding (Phase 3) reveals
  that the plan was wrong (not just the code), /implement appends
  corrective chunks to the tracker and re-gates in-session by spawning the
  review-plan agent directly (not by re-invoking /plan, which would
  regenerate the tracker), preserving completed chunks and looping under a
  bounded guard until the plan and code converge. /plan gained a
  /spec-style detect-existing-tracker branch so a re-run merges into the
  existing tracker instead of resetting completed work.
• spec_doc tracker field: /plan records the source spec path so
  /implement and review-impl bind to the exact spec instead of
  globbing the spec directory (sharpens spec -> tracker traceability).
• Shared concern vocabulary: the seven concerns common to review-plan
  (plan-time) and the Phase 3 checklist (code-time) are now documented as
  one vocabulary in quality-checklist.md, so the reviewers speak the same
  language at both altitudes (the eighth concern is phase-specific: TDD
  Quality of the plan vs Blindspots in the code).
• Three-state acceptance-criteria verification: review-impl
  classifies each criterion CONFIRMED / PLAUSIBLE / REFUTED, each backed by
  a quoted line, recall-biased (default PLAUSIBLE; only CONFIRMED when a
  real test would go red on regression). Ported from the red-team
  verification model.
• Spec validation evidence rule: every WARN/FAIL in the spec
  validation checklist must quote the exact spec line it refers to, the
  same discipline the review agents apply to code.
• validate.sh checks: a harness-agnosticism check fails if any
  harness-specific mechanic (Shift+Tab, Ctrl+G, /compact, /rename,
  --resume, and similar) reappears in the skill or agent prose; the
  structural suite (~220 checks) also enforces the three-skill layout,
  phase sequencing, JSON validity, no project-specific leaks, and no em
  dashes in any published file.
• Empirical validation: the higher-risk changes, the
  review-impl/red-team de-overlap (does a defect ever fall between
  them?) and the three-state false-positive catch, were validated with an
  A/B eval harness over seeded fixtures rather than by inspection alone.

Changed

• /implement is now build-only (3 phases): Load the Plan (locate the
  tracker, hard-stop unless its plan_review gate passed, orient on the
  next chunk), TDD Cycle per chunk (red/green/verify), and Quality
  Verification (8-point checklist + parallel review-impl + red-team
  gate). It refuses to start the TDD cycle on a tracker whose plan_review
  is missing or FAIL, telling the user to run /plan first.
• /spec hands off to /plan instead of /implement; its downstream
  mapping now routes spec sections to /plan (analysis, chunking) and
  /implement (tests) phases.
• Plan artifacts moved with the plan: tracker-schema.md and
  chunk-template.md now live under skills/plan/references/;
  quality-checklist.md stays under skills/implement/references/ (it is
  the Phase 3 code checklist). Each skill cross-references the one shared
  file it needs.
• review-impl narrowed to a conformance gate: it verifies plan match,
  acceptance criteria (with quoted test evidence), test quality, and
  regression only. Adversarial correctness, robustness/blindspots,
  standards violations, and cleanup are deferred to red-team, which
  already does them better. This removes the overlap between the two
  Quality-Verification reviewers while preserving their
  conformance-vs-correctness separation.
• Harness-agnostic instructions: removed terminal-specific mechanics
  from the skill prose in favor of portable behavior. Plan presentation
  states the principle (planning is read-only; present a plan; get explicit
  approval) and lets the harness supply the mechanism; context management
  and session resumption describe the intent instead of naming specific
  keystrokes or commands. Exploration and check-running steps use
  conditional phrasing: use a subagent or parallel-tool capability if the
  harness has one, otherwise sequential is the default. The workflow tables
  are retitled "Mapping to the Explore -> Plan -> Code Loop" with no harness
  brand in the header.
• review-plan / review-impl repointing: review-plan's description now
  says "in the /plan skill"; both agents read "the project's engineering
  PROJECT.md" rather than "PROJECT.md in the skill directory" (there are
  now three skills); review-impl's Criterion 5 and the checklist
  reference /implement Phase 3 (Quality Verification). Agent names are
  unchanged (review-plan, review-impl, red-team).
• review-plan Criterion 1 renamed "Scope, Completeness & Traceability"
  with explicit spec -> plan -> tracker forward/backward traceability
  language.
• Scaffolding trim: default to continuing multi-chunk work in one
  session rather than resetting between chunks; reset only when context
  degrades. Chunk decomposition prefers the fewest independently-testable
  chunks.

Migration

• The workflow gains one user-invoked step: after /spec, run /plan,
  then /implement. Trackers created by an older /implement run without
  a plan_review field will be refused by the new /implement; run
  /plan (pointed at the existing tracker/spec) to gate them, or set
  plan_review manually if the plan was already reviewed. Hand-setting
  plan_review: "PASS" bypasses the review-plan gate: /implement trusts
  the field and cannot tell a gate-written verdict from a typed one.

Fixed (design stress-test)

Hardening from an adversarial review of the whole v3.0.0 design:

• Plan-time gate crash-safety, the symmetric twin of the convergence
  fix. /plan creates the tracker with plan_review: "PENDING" (never a
  pre-stamped PASS), writes FAIL to disk before re-running on a gate
  FAIL, and bounds the FAIL/re-run loop, so a crash mid-review can no
  longer leave a stale PASS that /implement would build against.
• error and in_progress chunks are no longer dead-ends. error is
  documented as non-terminal (re-entered like in_progress); /implement
  Phase 1.3 validates the chunk graph (rejecting depends_on cycles and
  dangling ids); resumption re-enters an unfinished chunk before searching
  for the next pending one, so a blocked feature is surfaced, not
  silently left with the Phase 3 gate un-triggered.
• Convergence re-gate loop is now counted. convergence_rounds is
  bumped before each review-plan re-gate (not only when chunks are
  appended), so the two-round cap bounds the re-gate loop too; a bail-out
  cleanup path is documented.
• Spec back-edge. A finding that an acceptance criterion itself is
  wrong now routes to /spec (update mode) instead of into the plan gate
  built to reject it.
• Honest degradation without subagents / without a project rule file.
  The gates document that a harness with no subagent capability degrades
  to a non-isolated self-check; /implement Phase 3 covers standards and
  architecture with a self-check when no PROJECT.md/CLAUDE.md exists
  (where red-team's conventions angle would otherwise return nothing).
• Docs. Softened the "1:1 gates" phrasing (/implement touches two
  gates via convergence); README's table notes review-plan's convergence
  spawn; tracker writes documented as atomic.

v2.5.0

Adds the red-team adversarial diff reviewer and rewires the implement skill around it, closes agnosticism gaps so the loop works across projects, fixes cross-file inconsistencies found in review, and removes every em dash from the repo.

Added

• red-team agent: adversarial diff reviewer porting the code-review + simplify engine (5 correctness angles, 4 cleanup angles, a runtime conventions angle, recall-biased 3-state verify, gap sweep). Modes: bugs, cleanup, both. Cleanup mode is a standalone tidy pass that can apply fixes.

Changed

• Phase 6 quality gate spawns review-impl + red-team in parallel via the Agent tool instead of invoking /code-review, which a skill cannot trigger from the main loop.
• red-team is no longer git-only: shows git as the common case but instructs substituting another VCS or asking for the changed set, and treats a tracker/plan path as context, not the review target.
• /implement degrades gracefully with no PROJECT.md: infers and confirms build/test commands, notes the miss, suggests creating one.
• Conditional post-implementation docs; calibration guidance for strong-instruction-following models.

Fixed

• review-impl no longer flags a missing post-impl doc as a false finding on small changes.
• Plan-review gate branches on PASS-WITH-WARNINGS (the real verdict), not WARN.
• /implement reads the spec directory from PROJECT.md, matching /spec.
• README documents both PROJECT.md templates and the project-configs examples.

Removed

• The extension.yml spec-kit manifest; plugin.json is the single source of truth.
• Dependency on /code-review from within the implement skill.
• Every em dash, replaced with standard punctuation.

v2.0.0

Changed (breaking)

• Renamed /tdd to /implement. The slash command is now /implement <feature>. Speckit command ID is speckit.dev-workflow.implement (alias speckit.implement); the previous speckit.dev-workflow.tdd ID no longer resolves. Skill directory moved from skills/tdd/ to skills/implement/.
• Tracker filename convention is now impl-tracker-<feature>.json. The previous tdd-tracker-*.json prefix is no longer recognized by review-plan / review-impl.
• Phase 6 parallel reviewer is now /code-review (read-only) instead of /simplify (which writes to the tree). Running a writer concurrently with review-impl was racy; the review pair is now both read-only.
• This repo is now the only distribution channel. openkash/ai-agent-spec-skill and openkash/ai-agent-tdd-skill are deprecated; the spec-sync workflow and sync.sh script have been removed. Install via the Claude Code plugin or copy directly from this repo.

Added

• UI state-holder vs rendering-only distinction in the test-strategy table. UI chunks that introduce mutableStateOf, LaunchedEffect/useEffect, hoisted state, or input transformation must extract a state holder and unit-test its transitions. Pure prop/callback threading with no logic keeps the "no test" exemption.
• Both review-plan and review-impl now check the state-holder exemption explicitly. A chunk that claims "Pure UI — no test" while introducing a holder is flagged as a FAIL.
• Small-feature shortcut keeps both review gates. Only Plan Mode (Phase 2.4) and chunk decomposition (Phase 2.1-2.2) collapse for 1-chunk features; review-plan and review-impl + /code-review still run.

Migration

• Replace any saved /tdd <feature> invocations with /implement <feature>.
• Rename existing in-flight tracker files from tdd-tracker-*.json to impl-tracker-*.json if you want them picked up by the agents on resumption.
• Update any project-level docs or onboarding notes that reference skills/tdd/ to skills/implement/.
• If you customised skills/tdd/PROJECT.md, copy it to skills/implement/PROJECT.md before pulling — the directory rename means the old path will not exist after the update.
• The resume field on tracker chunks has been removed; per-chunk pattern hints and pitfalls now live in the optional notes field.

v1.0.0

Initial Release

A complete development workflow for Claude Code: specify, plan, review, implement, verify.

Included

• /spec skill — structured specification with user stories, acceptance criteria, interactive clarification (max 5 questions), 9-category ambiguity taxonomy, and 8-point validation
• /tdd skill — test-driven development with chunk decomposition, dependency graphs, JSON tracker with per-chunk resume fields, and red-green-refactor cycle
• review-plan agent — independent 8-point plan review running in isolated context to eliminate author-evaluator bias
• review-impl agent — independent 8-point implementation review running in isolated context for plan conformance, acceptance criteria, test quality, and drift detection
• Claude Code plugin format with auto-discovery
• Project-specific configuration via PROJECT.md templates
• Example configs for Android/Kotlin, TypeScript/Node, Python/Django, Python/pytest, Rust/CLI, Rust/Cargo

Install

git clone https://github.com/openkash/ai-agent-dev-workflow.git .claude/plugins/dev-workflow