@codebehind/agent-workflow

A scaffolding CLI that installs the agent-workflow spec-driven delivery framework into any repository.

The framework gives AI agents (Claude Code) a structured way to work: write specs, plan implementations, verify acceptance criteria, and hand off via GitLab merge requests — all with human checkpoints where you want them.

Quick start

npx @codebehind/agent-workflow init

Run this from the root of any repo (meta repo, monorepo, or single-purpose repo). It copies the full framework into place and prints next steps.

Use --force to overwrite existing files:

npx @codebehind/agent-workflow init --force

What gets installed

.agent-workflow/
  README.md                    ← workflow rules for agents
  acceptance-verification.md   ← acceptance proof protocol
  playwright-acceptance.md     ← UI verification guide
  notion-spec-mapping.md       ← Notion → spec mapping rules
  specs/_template.md           ← spec template
  plans/                       ← agent-generated plans
  docs/                        ← feature documentation
  artifacts/                   ← acceptance proof artifacts

.claude/
  rules/agentic-workflow.md    ← Claude Code session rules
  settings.json                ← permissions config
  skills/
    prepare-spec/SKILL.md      ← /prepare-spec skill
    implement-spec/SKILL.md    ← /implement-spec skill
    acceptance-proof/SKILL.md  ← /acceptance-proof skill
    create-mr-summary/SKILL.md ← /create-mr-summary skill

scripts/agent/                 ← GitLab helper scripts (glab-based)

AGENTS.md                      ← agent onboarding instructions
agents-workflow-dev-process.md ← human user manual
agents-workflow-env-setup.md   ← one-time environment setup guide

Workflow overview

| Phase | What happens | Skill | |-------|-------------|-------| | A — Prepare spec | Create or refine a spec (draft) | /prepare-spec | | B — Implement spec | Plan → code → docs for an open spec | /implement-spec |

See agents-workflow-dev-process.md after init for the full Claude Code workflow.

After init

1. Customize AGENTS.md and agents-workflow-dev-process.md for your project context.
2. Add a CLAUDE.md at the repo root with project-specific AI instructions (domain, architecture, conventions).
3. Make scripts executable: chmod +x scripts/agent/*.sh
4. Install prerequisites: glab, jq, node >= 18 — see agents-workflow-env-setup.md.
5. Write your first spec: copy .agent-workflow/specs/_template.md to .agent-workflow/specs/my-feature.md.

Requirements

• Node.js 18+
• glab (GitLab CLI) for MR management
• jq
• Claude Code CLI

Versioning

This package follows semver. Breaking changes to the framework structure increment the major version. To upgrade an existing installation:

npx @codebehind/agent-workflow init --force

Review the diff carefully — files you've customized for your project will be overwritten.