convez.ai
Skill
houseofwolvesllc

claudescrumskill

houseofwolvesllc/claudescrumskill

Ver no GitHub
InicialPluginScore · de 0 a 100

Claude Code skills for scrum project management — PRD to production release pipeline.

Instalação

$npx convez-ai houseofwolvesllc/claudescrumskill

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
50%
Último commit
há 2 meses
Versão
—
Issues abertas
0
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

Claude Scrum Skill

An open-source npm package of Claude Code skills that give you a complete scrum pipeline — from PRD to production release — with Claude as your scrum master. Works with local file-based backlogs, GitHub Projects, Jira, or Trello.

Includes project scaffolding, sprint planning, status tracking, sprint releases, full-project emulation testing, autonomous orchestration, and project cleanup.

Manual mode — you invoke each skill:

PRD  -->  /project-scaffold  -->  backlog (local, GitHub, Jira, or Trello)
                                      |
                                /sprint-plan --> populate the next sprint
                                      |
                               Claude works stories --> commits to release branch
                                      |
                                /sprint-status --> check progress anytime
                                      |
                               /sprint-release --> wrap up sprint, merge to development
                                      |
                                 You review   --> merge to main when ready
                                      |
                                /sprint-plan  --> next cycle

Autonomous mode — one command drives the full lifecycle:

PRD (optional)  -->  /project-orchestrate
                           |
            +----- Epic Completion Loop ------+
            |  /sprint-plan --> execute stories |
            |  --> /sprint-release --> merge    |
            |  --> branch cleanup --> repeat    |
            +----------------+-----------------+
                             |
            +--- Emulation Hardening Loop ----+
            |  /project-emulate --> findings   |
            |  --> generate PRD --> scaffold   |
            |  --> fix sprints --> re-emulate  |
            +----------------+-----------------+
                             |
                    Production-ready codebase

Table of Contents


Installation

v2.0.0 runtime requirement: v2.0.0 invokes Claude Code's Workflow tool for internal fan-out. Your Claude Code must include the Workflow tool (latest CLI, desktop app, web app, and IDE extensions all do). If you're on a stale CLI install without auto-update, run npm update -g @anthropic-ai/claude-code first — or install the v1.8.x fallback: npm install --save-dev @houseofwolvesllc/claude-scrum-skill@1.8.1.

npm (recommended)

# Global install — available in all projects
npm install -g @houseofwolvesllc/claude-scrum-skill

# Local install — this project only (developer tooling → devDependencies)
npm install --save-dev @houseofwolvesllc/claude-scrum-skill
# or the shorthand:
npm install -D @houseofwolvesllc/claude-scrum-skill

Global install copies skills to ~/.claude/skills/. Local install copies them to <project>/.claude/skills/ and adds .claude-scrum-skill to your .gitignore.

Why --save-dev? This package is developer tooling — the skills are consumed by Claude Code at planning/build/iteration time, never by your application's runtime. Saving to devDependencies (instead of dependencies) keeps it out of production installs (npm ci --production, NODE_ENV=production, Docker production layers), avoids running the postinstall script in environments where ~/.claude/skills/ doesn't exist, and accurately reflects that the package isn't a runtime requirement. Same category as eslint, prettier, vitest, etc.

Skills surface in Claude Code with their plain names: /project-scaffold, /project-orchestrate, /sprint-plan, etc.

Heads-up on re-installs: the postinstall script overwrites every file under <install-dir>/skills/ with the package's shipped version. If you've customized <install-dir>/skills/shared/config.json (e.g., changed paths.specs or paths.adr), back it up before re-running npm install and restore your values afterward. Skill files outside the shipped set are left alone — only files that exist in the package are overwritten.

Claude Code Plugin (alternative)

/plugin marketplace add houseofwolvesllc/claudescrumskill
/plugin install claude-scrum-skill@houseofwolvesllc

This installs all skills as a native Claude Code plugin with automatic updates. To update later:

/plugin marketplace update

Important difference from npm install: Claude Code namespaces plugin-installed skills with the marketplace identifier to prevent collisions between plugins. Skills surface as /@houseofwolvesllc/project-scaffold, /@houseofwolvesllc/project-orchestrate, etc. — not as /project-scaffold and /project-orchestrate. If you prefer the plain names, use the npm install path above; if you prefer the marketplace UI for discovery and updates, use this path and live with the namespace.

Manual

Clone the repo and copy the skills/ contents into ~/.claude/skills/ (global) or <project>/.claude/skills/ (per-project). All skill directories must be siblings under the same parent, with shared/ alongside them — skills reference ../shared/references/ via relative paths.

The manual path produces the same plain-name UX as npm install (both bypass the plugin layer's namespacing), but you forfeit automatic updates.

Note: After installing, restart Claude Code for the skills to become available.


Configuration

All configuration lives in skills/shared/config.json:

{
  "scaffolding": "local",
  "paths": {
    "specs": ".claude-scrum-skill/specs",
    "adr": ".claude-scrum-skill/adr",
    "backlog": ".claude-scrum-skill/backlog",
    "context": ".claude-scrum-skill/context"
  },
  "scaffold": {
    "two_pass_threshold_words": 5000,
    "design_spike_enabled": true
  },
  "jira": {
    "project_key": ""
  },
  "trello": {
    "board_id": ""
  }
}

Scaffolding Modes

ModeDescriptionAuth Required
localFile-based backlog in your project directory (default)None
githubGitHub Issues, Milestones, and Projectsgh CLI
jiraJira Cloud issues, epics, and sprintsEnv vars
trelloTrello boards, lists, and cardsEnv vars

Two-Pass Mode

For large PRDs, /project-scaffold automatically switches from single-pass to two-pass scaffolding. Pass 1 extracts only the epic skeleton (one agent reads the whole PRD); Pass 2 spawns one focused subagent per epic to elaborate that epic's stories. Per-epic context stays tight regardless of PRD size, so the last epic's stories are as well-specified as the first.

Triggers (first match wins):

  1. PRD frontmatter scaffold_mode: single-pass | two-pass (explicit override)
  2. CLI flag --mode single-pass | two-pass
  3. PRD word count exceeds scaffold.two_pass_threshold_words (default 5000)

If Pass 1 finds ≤ 2 epics, scaffolding auto-downgrades to single-pass elaboration since the two-pass overhead isn't justified at that scale. Failures retry once and degrade gracefully — Pass 1 falls back to single-pass; Pass 2 marks the affected epic's stories needs-context and lets sibling subagents continue.

The chosen mode and reasoning are announced before scaffolding begins, so you always know why a given path was taken.

Design-Spike Epic

When /project-scaffold runs two-pass on a multi-epic PRD, it auto-injects a research-driven design-spike epic at the head of the project. This epic's stories (all persona: research) produce:

  • One foundational ADR at <paths.adr>/NNNN-<slug>.md
  • One per-implementation-epic CONTEXT.md at <paths.context>/<epic-slug>/CONTEXT.md

Implementation epics are gated on the design-spike epic via the existing blocked_by mechanism, so no implementation story enters a sprint until its CONTEXT.md exists. During execution, /project-orchestrate subagents read CONTEXT.md in addition to CLAUDE.md before writing code — its naming, file layout, types, and patterns sections override generic CLAUDE.md conventions for that epic. This gives every parallel subagent a shared anchor, eliminating the cross-story drift that otherwise compounds before the sprint review gate.

Triggers (first match wins):

  1. PRD frontmatter design_spike: true | false
  2. CLI flag --design-spike | --no-design-spike
  3. scaffold.design_spike_enabled config (default true)
  4. Auto-trigger: two-pass mode + > 1 implementation epic

Artifacts are committed to the development branch via the filesystem in all backends — git is the universal substrate. Remote backends may surface links via milestone/epic descriptions but the committed files are the single source of truth.

Detection signal is the type:design-spike label (GitHub/Trello/Jira) or epic_type: design-spike frontmatter field (local). The default epic title is "Architecture & Design" but the title is not load-bearing.

Configurable Paths

PathDefaultPurpose
paths.specs.claude-scrum-skill/specsSpec documents from /spec
paths.adr.claude-scrum-skill/adrArchitecture Decision Records
paths.backlog.claude-scrum-skill/backlogLocal backlog files (local mode only)
paths.context.claude-scrum-skill/contextPer-epic CONTEXT.md files produced by the design-spike epic

To check these files into version control (e.g., docs/adr), change the path and it won't be covered by the .gitignore entry for .claude-scrum-skill.

Scaffolding Behavior

KeyDefaultPurpose
scaffold.two_pass_threshold_words5000PRD word count above which two-pass scaffolding auto-triggers
scaffold.design_spike_enabledtrueGlobal enable switch for the design-spike pre-epic

Quick Start

Local Mode (default — no setup required)

  1. Write a PRD — Create a markdown file describing your project, epics, and stories.

    Optionally include YAML frontmatter to override the auto-detected scaffolding behavior:

    ---
    title: My Project
    scaffold_mode: two-pass     # force two-pass even for a small PRD
    design_spike: false         # suppress the design-spike epic even when triggered
    ---
    

    Both fields are optional — omit them to use the word-count heuristic and the auto-injection rules described in Two-Pass Mode and Design-Spike Epic.

  2. Scaffold the project:

    /project-scaffold path/to/prd.md
    

    This creates a local backlog with epic directories and story files in .claude-scrum-skill/backlog/.

  3. Plan a sprint:

    /sprint-plan
    
  4. Work stories — Tell Claude to pick up executor:claude stories from the sprint.

  5. Check progress:

    /sprint-status
    
  6. Release the sprint:

    /sprint-release
    
  7. Or go fully autonomous:

    /project-orchestrate path/to/prd.md
    

Remote Mode (GitHub, Jira, or Trello)

  1. Set "scaffolding" in config.json to "github", "jira", or "trello".
  2. Complete the provider setup for your chosen provider.
  3. Follow the same workflow above — the skills automatically use the configured provider's API.

Provider Setup

GitHub

Create a fine-grained Personal Access Token:

  1. Go to github.com/settings/personal-access-tokens and generate a new token.

  2. Grant these repository permissions:

    PermissionAccessWhy
    ContentsRead & WriteCreate branches, push commits
    IssuesRead & WriteCreate and update stories
    MetadataReadRequired by GitHub for all PATs
    Pull requestsRead & WriteOpen PRs for releases
  3. Grant this account permission:

    PermissionAccessWhy
    ProjectsRead & WriteCreate project boards and fields
  4. Authenticate the CLI:

    echo "YOUR_TOKEN" | gh auth login --with-token
    gh auth status
    

Security tip: Do not grant write access to main. Set up branch protection so merges to main always require your review.

Jira

  1. Generate an API token at id.atlassian.com/manage-profile/security/api-tokens.

  2. Set environment variables:

    export JIRA_SITE="https://yourcompany.atlassian.net"
    export JIRA_EMAIL="you@example.com"
    export JIRA_API_TOKEN="your-api-token"
    
  3. Optionally set the project key in config.json:

    {
      "scaffolding": "jira",
      "jira": {
        "project_key": "MYPROJ"
      }
    }
    
  4. If project_key is empty, /project-scaffold creates a new Scrum project automatically and saves the key back to config.json. If set, it uses the existing project.

Trello

  1. Get your API key from trello.com/power-ups/admin.

  2. Generate a token by visiting:

    https://trello.com/1/authorize?expiration=never&scope=read,write&response_type=token&key=YOUR_API_KEY
    
  3. Set environment variables:

    export TRELLO_API_KEY="your-api-key"
    export TRELLO_TOKEN="your-token"
    
  4. Optionally set the board ID in config.json:

    {
      "scaffolding": "trello",
      "trello": {
        "board_id": "your-board-id"
      }
    }
    

    Find your board ID by opening the board in Trello, adding .json to the URL, and looking for the "id" field.

  5. If board_id is empty, /project-scaffold creates a new board automatically and saves the ID back to config.json. If set, it uses the existing board.

Note: Trello has no native sprint, dependency, or story point support. Sprints are modeled as lists, points are stored in custom fields (or card title prefixes), and dependencies are tracked in card descriptions.


Skills Reference

SkillCommandWhat It Does
project-scaffold/project-scaffold <prd-path>Full project setup from PRD
spec/spec <prompt>Transform a rough idea into a structured spec document
sprint-plan/sprint-plan [owner/repo]Plan and populate the next sprint
sprint-status/sprint-status [owner/repo]Progress report and burndown
sprint-release/sprint-release [owner/repo]Close sprint, merge to development
project-emulate/project-emulateIntegration seams, layer contracts, cross-service payloads, full lifecycle walkthrough
project-orchestrate/project-orchestrate [prd] [repo]Autonomous lifecycle driver
project-cleanup/project-cleanup [path] [--fix]Build, lint, dead code, and test coverage

The [owner/repo] argument is only needed in GitHub mode. Jira, Trello, and local modes read from config.


Branch Strategy

All modes share the same git branch strategy:

main (human-only — requires your review)
 +-- development (sprint approval gate)
      +-- release/core-api
           +-- story/1-init-project     --> auto-merge
           +-- story/2-database-schema  --> auto-merge
           +-- story/3-auth-endpoints   --> auto-merge
  • Story --> Release branch: Auto-merge when CI passes (or direct merge in local mode)
  • Release --> development: PR review in GitHub mode, direct merge in local/Jira/Trello mode
  • development --> main: Always human-initiated

Personas

Stories can be assigned a persona that controls the posture of the subagent executing them during orchestration. Personas are defined in skills/shared/references/PERSONAS.md.

PersonaAssigned viaBehavior
impl (default)No label neededStandard implementation — write code, tests, open PR
opspersona:ops label or frontmatterOps/infra posture — idempotency, rollback, least privilege
researchpersona:research label or frontmatterResearch posture — output is a document (ADR/RFC), not code
reviewAutomatic (release gate)Reviews the release diff, reports findings by severity

During sprint planning, personas are assigned automatically based on story labels (e.g., scope:infra gets persona:ops). Override by manually setting the label or frontmatter before orchestration.


Autonomous Orchestration

/project-orchestrate chains all skills into a fully autonomous pipeline.

Invocation Patterns

FormBehavior
/project-orchestrateOrchestrates all open epics in the existing backlog.
/project-orchestrate spec.mdSingle-spec orchestration. Scaffolds the spec, runs the full lifecycle.
/project-orchestrate spec-1.md spec-2.md spec-3.mdSequential multi-path mode. Each spec receives its own complete orchestration (Phase 1 → Phase 2 → Phase 3 → ADR → state cleanup) end-to-end before the next begins. Each spec gets its own design-spike (if triggered), emulation pass, cleanup, and ADR.
/project-orchestrate owner/repoGitHub mode — orchestrates the named repo's open epics.
/project-orchestrate spec.md owner/repoGitHub mode — scaffolds the spec into the named repo, then orchestrates only that PRD's epics.
/project-orchestrate --merged spec-1.md spec-2.mdOpt-in merged mode. Treats inputs as one combined project with best-effort legacy behavior. Emits a warning that formal merged semantics are deferred to a follow-up spec — prefer the sequential default unless you need merged.

Multi-Path Flags

  • --skip-on-pause (default off) — when a spec's orchestration pauses on a safety gate, mark it skipped and advance to the next spec instead of pausing the queue. Use with caution; safety gates exist for a reason.
  • --merged (default off) — see the table above; opts into the legacy unified-multi-spec behavior.

Inter-Spec Dependencies

PRD documents can declare optional depends_on frontmatter to override the default argument-order execution:

---
title: Spec B
depends_on:
  - spec-a.md   # ensure spec-a runs before this one
---

/project-orchestrate resolves the dependency graph at run start (topological sort, ties broken by argument order) and aborts before any spec executes if a cycle or missing dependency is detected. See CONVENTIONS.md → Frontmatter Fields → PRD Document Frontmatter for the full convention.

Phase 1 — Epic Completion Loop

  1. Scaffolds the PRD (if provided) or reads existing backlog. On large or multi-epic PRDs, scaffolding runs in two-pass mode and auto-injects a design-spike epic at position 0
  2. Plans sprints via /sprint-plan — the design-spike epic (when present) executes first, producing the ADR and per-epic CONTEXT.md files that seed the implementation epics
  3. Executes executor:claude stories in parallel via subagents with persona routing — implementation subagents read their epic's CONTEXT.md in addition to CLAUDE.md before writing code
  4. Releases via /sprint-release
  5. Runs automated review gate (using the review persona)
  6. Merges to development and cleans up branches
  7. Repeats until all epics are complete

Phase 2 — Emulation Hardening Loop

  1. Runs /project-emulate to discover issues
  2. Generates a hardening PRD from critical/warning findings
  3. Scaffolds and executes a hardening epic
  4. Re-emulates until clean (safety valve at 3 runs)

Phase 3 — Project Cleanup

  1. Runs /project-cleanup --fix across the entire codebase
  2. Reviews and updates ADRs based on decisions made during orchestration
  3. Cleans up the orchestration state file

State Persistence

Orchestration state is saved to .claude-scrum-skill/orchestration-state.md. If Claude hits a usage cap or the session restarts, it picks up exactly where it left off.

Safety Boundaries

  • Merges to development are pre-authorized
  • Merges to main are never automatic
  • Failed stories are retried once, then marked blocked
  • Merge conflicts pause orchestration and escalate to you
  • After 3 hardening runs, Claude pauses and asks for guidance
  • Review gate can be skipped with ORCHESTRATE_SKIP_REVIEW=1

Customization

Sprint Length

Edit shared/references/CONVENTIONS.md > "Sprint Cadence". Default: 2 weeks.

Velocity Target

/sprint-plan asks for velocity or defaults to 20 story points.

Label Colors

Defined in project-scaffold/SKILL.md. Modify to match your preferences.

Executor Criteria

Edit shared/references/CONVENTIONS.md > "Executor Assignment Guidelines".

Personas

Edit shared/references/PERSONAS.md to add or modify persona preambles.

Output Paths

Edit shared/config.json to change where specs, ADRs, and backlog files are written. Point them to a non-dotfile path (e.g., docs/adr) to include them in version control.

Adding Epics

Run /project-scaffold with a new PRD — it detects the existing project and offers to add stories to existing epics or create new ones.


Architecture (v2.0.0+)

claudescrumskill ships in two cooperating layers. The split is documented in detail in ADR-0003.

┌────────────────────────────────────────────────────────────┐
│  Skills — markdown SKILL.md (the opinion + the surface)    │
│  - Slash commands users type                                │
│  - Phase / step structure                                   │
│  - Durable repo artifacts (state files, ADRs, CONTEXT.md)   │
│  - Installed at ~/.claude/skills/<skill>/SKILL.md           │
└──────────────────────┬─────────────────────────────────────┘
                       │  invokes via Workflow tool
                       ▼
┌────────────────────────────────────────────────────────────┐
│  Workflows — JavaScript at lib/workflows/ (the substrate)  │
│  - Fan-out (parallel, pipeline) up to 16 concurrent agents  │
│  - Schema-validated structured returns                      │
│  - Journal-based in-session resume                          │
│  - Installed at ~/.claude/skills/_workflows/                │
└──────────────────────┬─────────────────────────────────────┘
                       │  spawns
                       ▼
┌────────────────────────────────────────────────────────────┐
│  Agents — the workers that implement stories, review        │
│  diffs, verify findings, etc.                               │
└────────────────────────────────────────────────────────────┘

Workflow scripts shipped in v2.0.0

ScriptPurposeUsed by
sprint_pipeline.jsper-story pipeline: implement → review → verify → openPR/project-orchestrate Phase 1 Step 3
elaborate_epics.jsPass 2 of two-pass scaffolding, in parallel/project-scaffold
adversarial_verify.jsclaimant/skeptic/judge per emulation finding/project-emulate
review_panel.jsmulti-lens (correctness/security/style/tests) review/project-cleanup, /code-review

Schemas at lib/workflows/schemas/

JSON Schema Draft 2020-12. The cross-skill type system: SpecSchema, EpicSchema, StorySchema, EmulationFindingSchema, ReviewVerdictSchema, SprintStoryReturnSchema, ScaffoldOutputSchema, PRDFrontmatterSchema. Schemas live alongside workflows and are referenced from agent({ schema: ... }) calls.

Adding a workflow

Contributors adding fan-out heavy skills (large parallel work, multi-stage pipelines, judge panels) should:

  1. Author the workflow at lib/workflows/<name>.js per the patterns in existing scripts.
  2. Add any new schemas to lib/workflows/schemas/.
  3. Reference the workflow from the skill markdown via the Path Resolution Algorithm documented in each affected SKILL.md (<skills-root>/_workflows/<name>.js).
  4. Bump the package version per SemVer (new workflow + new schema → minor; breaking schema change → major).

Shared References

All skills reference shared configuration and standards from skills/shared/:

skills/shared/
  +-- config.json                 # mode, paths, provider settings
  +-- references/
       +-- CONVENTIONS.md         # labels, branches, fields, estimation
       +-- PERSONAS.md            # subagent role preambles
       +-- PROVIDERS.md           # GitHub/Jira/Trello API reference

Tips

  • Start with local mode. No setup required — scaffold a PRD and start working immediately.
  • Branch protection is your safety net. The PAT should not have write access to main.
  • Run /project-emulate before releases to catch integration seam failures, layer contract mismatches, and permission gaps.
  • Run /project-cleanup --fix after major changes to enforce build/lint cleanliness and test coverage.
  • Chunk large epics into multiple sprints for natural review gates.
  • Jira/Trello users: If no project key or board ID is configured, /project-scaffold creates one automatically (Scrum template for Jira).
  • Author large PRDs with explicit architectural intent. Sections describing shared types, naming conventions, file layout boundaries, and cross-cutting patterns give the design-spike epic concrete material to lift into the project's foundational ADR and per-epic CONTEXT.md files — the better your PRD spells these out, the more consistent your parallel implementation subagents will be.
  • For related specs, declare depends_on in PRD frontmatter rather than relying on argument order. /project-orchestrate will topologically sort the queue and abort on cycles or missing deps before any spec runs — catches ordering mistakes up front instead of mid-orchestration.

License

Apache 2.0 — See LICENSE for details.

Ver o original no GitHub

Bom para

Relacionados