argus-speckit

Spec-kit slash-command bridge for argus-qa. Installs five /speckit.argus-* slash commands into a project's .claude/commands/ directory and a project-local QA Constitution at .specify/memory/argus-qa-constitution.md so Claude Code can drive the Argus QA agent under a versioned governance contract.

• Zero runtime dependencies.
• Node.js >= 18.
• argus-qa ^1.5.0 is a peer dependency (install separately).
• Ships a 9-article QA Constitution that is enforced at a Phase -1 gate by every other command.

Installation

# 1. Install the underlying Argus QA agent (one time per project).
npx argus-qa init

# 2. Install the slash commands + the QA Constitution from this package.
npx argus-speckit init

Both commands are idempotent. Run them again whenever you upgrade the corresponding npm package.

After install, run /speckit.argus-constitution once to seed the constitution placeholders, then commit .specify/memory/argus-qa-constitution.md so every contributor shares the same governance document.

Prerequisites

| Prerequisite | Why | |---|---| | Node.js >= 18 | Required for npx and the CLI. | | argus-qa ^1.5.0 installed in the project | The slash commands activate the argus and knowledge-base agents that argus-qa installs under .claude/agents/. If argus-qa is not present, the slash commands will refuse to run and instruct you to install it. | | Argus QA Constitution at .specify/memory/argus-qa-constitution.md | All four enforcement commands fail fast without it. Run /speckit.argus-constitution to seed it. | | Playwright (for /speckit.argus-generate and /speckit.argus-verify) | The generated tests and the verify runner both use @playwright/test. | | gh CLI, authenticated (for /speckit.argus-ticket against GitHub) | Used to fetch issue bodies/comments and to post the enrichment comment. Run gh auth login once. | | jira CLI or JIRA_BASE_URL + JIRA_EMAIL + JIRA_API_TOKEN env vars (for /speckit.argus-ticket against Jira) | Used to fetch the Jira issue and post the enrichment comment. The REST fallback kicks in automatically when the CLI is absent. |

End-to-end workflow

The five commands are designed to chain:

/speckit.argus-constitution  →  (once, at onboarding — seed the QA Constitution)
/speckit.argus-doc           →  (once, at onboarding — build the project knowledge base)
/speckit.argus-ticket        →  pull a ticket, draft a Dev/QA plan, enrich the ticket with ACs + test cases
/speckit.argus-generate      →  turn the enriched spec into Playwright tests
/speckit.argus-verify        →  run the tests, map failures back to the originating ACs

Everything is idempotent and saves run manifests under .argus/. Every artifact is stamped with the active constitution version, so a future amendment knows exactly which artifacts need regenerating.

Governance — the Argus QA Constitution

argus-speckit 1.2 adds a 9-article QA Constitution at .specify/memory/argus-qa-constitution.md. It is the governance contract that every other slash command reads and enforces at a Phase -1 gate before producing its primary artifact. If the constitution is missing, /speckit.argus-ticket, /speckit.argus-generate, /speckit.argus-verify, and /speckit.argus-doc all fail fast with:

Argus QA Constitution not found. Run /speckit.argus-constitution to install.

The nine articles

| # | Article | Enforces | |---|---|---| | I | Specification Authority | spec.md is the only source of truth | | II | AC-First Imperative | every test traces to a numbered AC via traceability.json | | III | Test-First Within QA | ACs and test cases authored before test code | | IV | Real-Environment Integration | prefer real APIs/browsers over heavy mocking | | V | Determinism Non-Negotiable | no arbitrary timeouts; explicit waits only | | VI | Idempotency | every command safe to re-run; updates in place | | VII | Simplicity Gate | ≤3 test-project roots; no future-proofing | | VIII | Anti-Abstraction Gate | Playwright APIs used directly; no DSL layers | | IX | Traceability & Living Documentation | every artifact carries the constitution version |

Each article ships with a Principle, a Rationale, a Gate Mapping, and an Exception Protocol that points at a Complexity Tracking section in the artifact.

How amendments work

/speckit.argus-constitution                          # first run — seeds the file
/speckit.argus-constitution Article V should …       # amendment — proposes a semver bump

/speckit.argus-constitution:

1. On first run, fills [PROJECT_NAME], [RATIFICATION_DATE], [VERSION] (= 1.0.0), and [LAST_AMENDED_DATE].
2. On amendment, refuses if the working tree has uncommitted changes to the constitution (use --force to override). Proposes a semver bump per the rules below, applies the amendment in-place, and emits a Sync Impact Report at the bottom of the file listing every dependent artifact (slash commands and .argus/** runs) as ✅ updated or ⚠ pending.

| Bump level | Triggered by | |---|---| | MAJOR | removing or redefining an article | | MINOR | adding a new principle, article, or gate | | PATCH | wording / clarity changes |

Customisation policy

The constitution is committed by consumers (it is intentionally not in .gitignore). argus-speckit update will refuse to overwrite a customised constitution unless you pass --force. Use /speckit.argus-constitution instead — it performs a guided amendment that preserves your edits and bumps the version.

The slash commands

After argus-speckit init, Claude Code will auto-discover five new commands from .claude/commands/:

/speckit.argus-constitution [amendment instructions]

Bootstrap or amend the QA Constitution. Run with no arguments on first install to seed .specify/memory/argus-qa-constitution.md with v1.0.0. Run with an amendment description to propose a semver bump and emit a Sync Impact Report.

/speckit.argus-constitution
/speckit.argus-constitution Tighten Article V to forbid all timeouts above 100ms
/speckit.argus-constitution --force        # bypass the dirty-working-tree check

/speckit.argus-ticket <provider> <ticket-id>

Pull a full specification from GitHub or Jira, draft a Dev/QA plan, wait for your approval, and then enrich the ticket itself with detailed acceptance criteria and test cases. The original ticket description is never overwritten — the enrichment is posted as a new comment (GitHub) or a new comment (Jira). If a previous Argus enrichment already exists, it is updated in place rather than duplicated.

The plan now includes a Phase -1 QA Gate section near the top, with the active constitution version stamped into run_manifest.json as constitutionVersion.

Provider + ticket-id forms:

| Provider | Accepted ticket-id forms | |---|---| | github / gh | 45, owner/repo#123, a full GitHub issue URL, GH-123 | | jira | PROJ-123, a full Jira browse URL |

Two-phase flow:

1. Fetch + plan. The command fetches the ticket (including comments), normalises it into spec.md, then drafts a plan.md containing:
   • Phase -1 QA Gate (constitution version + checklist)
   • Summary, Dev workflow, QA workflow
   • Proposed acceptance criteria — numbered AC1…ACn in Given/When/Then form
   • Proposed test cases — grouped by AC, with id/title/preconditions/steps/expected/priority/type
   • Edge cases & risks, Open questions
2. Confirm + enrich. You review (and optionally edit) plan.md, then reply with approve, edit: <instructions>, or cancel. On approve, the command posts a single enrichment block back to the ticket (ACs, test-case tables, edge cases, QA checklist) and saves qa-artifacts.md, run_manifest.json, and traceability.json locally.

Artifacts written:

.argus/ticket/<provider>-<id>/
  raw.json              # provider response, untouched
  spec.md               # normalised specification (title, description, comments, existing ACs)
  plan.md               # Dev/QA plan — edit this before approving
  qa-artifacts.md       # copy of what was posted to the ticket
  run_manifest.json     # ticketKey, provider, timestamps, AC/test counts, constitutionVersion
  traceability.json     # AC → test-case id map (consumed by /speckit.argus-generate)

Examples:

/speckit.argus-ticket github 45
/speckit.argus-ticket github owner/repo#123
/speckit.argus-ticket jira PROJ-123
/speckit.argus-ticket jira PROJ-123 --phase=fetch     # stop after drafting the plan
/speckit.argus-ticket jira PROJ-123 --phase=implement # re-post enrichment from the edited plan
/speckit.argus-ticket github 45 --force               # re-fetch + re-enrich (updates existing comment)

/speckit.argus-generate [spec-file-or-ticket-id] [app-url]

Generate Playwright TypeScript E2E tests from acceptance criteria. Accepts a spec file path, a ticket identifier, or a bare app URL. Writes .spec.ts files under tests/argus-generated/ and a run manifest + traceability JSON under .argus/generate/spec-<hash>/. Refuses to run if the constitution is missing or its [VERSION] placeholder is unfilled.

/speckit.argus-generate specs/login.md http://localhost:3000
/speckit.argus-generate PROJ-123

/speckit.argus-doc [target-dir] [output-dir]

Generate or refresh the project knowledge base using the Argus Knowledge Base agent. Scans the target directory (default: project root), detects the technology stack, and writes structured markdown documentation to the output directory (default: docs/). Writes a run manifest under .argus/kb/run_manifest.json with constitutionVersion stamped. Each generated markdown file ends with _Generated under Argus Constitution v[VERSION]._.

/speckit.argus-doc
/speckit.argus-doc apps/api docs/api

/speckit.argus-verify [test-pattern] [app-url]

Run the Playwright tests previously generated and capture a regression report. Maps failed tests back to their originating acceptance criteria via .argus/generate/*/traceability.json. Writes results.json, run_manifest.json, traceability.json, and a human-readable report.md under .argus/verify/<run-id>/. Failed gates are flagged with 🔴 at the top of report.md.

/speckit.argus-verify
/speckit.argus-verify "tests/argus-generated/checkout/**/*.spec.ts" https://staging.myapp.com

CLI

argus-speckit <command> [options]

Commands:
  init        Install the 5 slash commands + QA Constitution.
  update      Re-copy slash commands. Preserves a customised constitution unless --force.
  status      Show which files are installed / missing / outdated / customised.
  uninstall   Remove the slash command files. The constitution is preserved by default.
  version     Print the argus-speckit version.
  help        Show usage.

Options:
  --force                  Overwrite files that already exist. For `update`, also
                           overwrites a customised QA Constitution.
  --dry-run                Show what would happen without writing anything.
  --yes                    Skip interactive confirmation prompts.
  --include-constitution   (uninstall only) Also remove the QA Constitution.
                           Off by default — it may contain irreplaceable customisation.

What gets written to your project

.claude/commands/speckit.argus-ticket.md           # gitignored
.claude/commands/speckit.argus-generate.md         # gitignored
.claude/commands/speckit.argus-doc.md              # gitignored
.claude/commands/speckit.argus-verify.md           # gitignored
.claude/commands/speckit.argus-constitution.md     # gitignored
.specify/memory/argus-qa-constitution.md           # COMMITTED (governance — not gitignored)
.gitignore                                         # amended: ignores the five command files

argus-speckit manages exactly those six files plus the .gitignore block. Everything else under .claude/ belongs to argus-qa or to you. The constitution at .specify/memory/argus-qa-constitution.md lives side-by-side with your spec-kit constitution.md; the two files are siblings, never merged.

Programmatic API

const speckit = require('argus-speckit');

// Install — slash commands + constitution.
speckit.install({ force: false, dryRun: false, forceGovernance: false });

// Status — includes a `customised` field for governance drift.
const { installed, missing, outdated, customised } = speckit.status();

// Constitution helpers.
const c = speckit.getConstitutionStatus();
// → { present, path, version, lastAmendedDate, ratificationDate, projectName, drift }

speckit.bumpConstitutionVersion('minor');
// → { from: '1.0.0', to: '1.1.0', path, lastAmendedDate }

speckit.seedConstitutionPlaceholders({ projectName: 'my-app' });

// Uninstall — preserves the constitution by default.
speckit.uninstall(false, { includeConstitution: false });

console.log(speckit.INSTALL_MANIFEST);   // 6 entries, each with a `category` field
console.log(speckit.version);

Uninstalling

# Remove only the slash commands. The QA Constitution is preserved.
npx argus-speckit uninstall

# Remove the slash commands AND the QA Constitution.
npx argus-speckit uninstall --include-constitution

This removes the five slash command files (and, if --include-constitution is set, the QA Constitution) plus the empty .claude/commands/ directory if no other commands remain. It does not touch argus-qa or the rest of .claude/.

Migration from 1.1.x

If you already have argus-speckit 1.1.x installed:

# Update slash commands. Your constitution will not be created automatically by
# this command — see step 2.
npx argus-speckit update

# Seed the new QA Constitution.
/speckit.argus-constitution

What changes for you:

• A fifth slash command /speckit.argus-constitution is now installed alongside the four you already have.
• A new file .specify/memory/argus-qa-constitution.md is added by argus-speckit init (or seeded by the slash command above). Commit it — it is intentionally not gitignored.
• The four existing slash commands now refuse to run if the constitution is missing. They emit a Phase -1 QA Gate block in their primary artifact and stamp the active constitution version into every run manifest.
• argus-speckit update will no longer silently overwrite a customised constitution; pass --force if you really want to.
• argus-speckit uninstall preserves the constitution by default; pass --include-constitution to remove it.

License

MIT © Manoj Tyagi