An Anthropic-aligned execution framework that brings agile delivery discipline to Claude Code.

Quick Start  •  How It Works  •  Dashboard  •  Web UI  •  Documentation  •  Cross-Platform  •  Changelog

---

Why StoryForge?

Claude Code is powerful, but without structure it drifts. You start fixing a bug and end up refactoring three modules. A "quick feature" grows into an unplanned rewrite. Context is lost between sessions.

StoryForge solves this. It wraps Claude Code in a lightweight agile operating system:

• Every session starts with a board check — what's in progress, what's next
• Every piece of work maps to an Initiative > Feature > Story > Task hierarchy
• New ideas go to Backlog, not into the current scope
• A portfolio-orchestrator agent enforces discipline across all projects
• Work is not Done until implementation, tests, and artifacts are all updated

No external tools. No databases. Just markdown files, Claude Code primitives, and a clear process.

How It Works

StoryForge uses a thin global, rich project architecture. The global layer provides security and agents; each project carries its own delivery rules, hooks, and skills.

~/.claude/  (thin — security + agents)     Per-project  (rich — delivery)
  CLAUDE.md      (~27 lines, identity)       .claude/CLAUDE.md   (full delivery rules)
  settings.json  (deny rules, guardrails)    .claude/settings.json (hooks + deny rules)
  agents/        (8 agents)                  .claude/rules/      (kanban, discipline)
  skills/        (4 global skills)           .claude/skills/     (5 project skills)
                                             .kanban/
                                               board.md, backlog.md, sprint.md
                                               stories/, decisions.md, changelog.md

Layer	What it provides
Global (~/.claude/)	Identity, anti-drift, security deny rules, PreToolUse guardrails, universal agents, global skills
Project (.claude/)	Full delivery rules, all hooks (SessionStart, PostToolUse, Stop, Notification), project skills, rules
Kanban (.kanban/)	Delivery tracking artifacts (board, stories, backlog, sprint, decisions, changelog)

Agents (8 — global)

Agent	Role
portfolio-orchestrator	Top-level coordinator. Checks the board, validates scope, delegates to specialists
planner	Creates initiatives, features, stories with acceptance criteria
implementer	Executes bounded work within the active story scope
reviewer	Verifies quality, story compliance, and artifact consistency
doc-maintainer	Updates board, changelog, decisions, and backlog
security-auditor	Post-sprint security review — scans for secrets, injections, misconfigs
upstream-watch	Monitors Anthropic docs for changes that affect StoryForge
upstream-monitor	Automated daily monitoring (sonnet model)

Skills

Global skills (4 — installed in ~/.claude/skills/)

Skill	Usage
/kanban-bootstrap	Initialize .kanban/ structure in any project
/release-adapt	Process an upstream Claude Code change
/security-audit	Run security scan (required before sprint closure)
/upstream-check	Check Anthropic docs for upstream changes

Project skills (5 — installed in .claude/skills/ by bootstrap)

Skill	Usage
/story-write	Create a new story with structured fields
/sprint-groom	Plan or review a sprint
/dashboard	Display the Kanban dashboard
/doc-update	Update delivery artifacts after work completes
/gh-link	Link a story to a GitHub issue or PR

Hooks (project-level)

All hooks are defined in the project's .claude/settings.json, not at the global level.

Event	Behavior
SessionStart	Reminds Claude to check .kanban/board.md before working
SessionStart (resume)	Re-injects board context on session resume
Stop	Reminds to update artifacts if changes were made (loop-safe)
PostToolUse	Reminds to update board when story files are edited
Notification	Alerts when Claude needs user input

Security (global-level)

Mechanism	What it does
Permission deny rules	Blocks access to .env, .ssh, .aws, gcloud, .azure, .kube, .docker, .npmrc, .git-credentials
PreToolUse guardrails	Blocks rm -rf /, force push, hard reset, chmod 777, pipe to bash (exit code 2)

Kanban Flow

  Backlog ──> Ready ──> In Progress ──> Review ──> Done
     │                       │                       │
     │  New ideas land       │  One story at a time  │  All criteria met
     │  here by default      │  Scope is fixed       │  Tests pass
     └───────────────────────┴───────────────────────┘  Artifacts updated

Quick Start

1. Install the global layer

Bash (macOS / Linux / Git Bash)	PowerShell (Windows)
git clone https://github.com/toonight/StoryForge.git cd StoryForge ./scripts/install_storyforge.sh	git clone https://github.com/toonight/StoryForge.git cd StoryForge .\scripts\install_storyforge.ps1

2. Bootstrap a project

cd /path/to/your-project

# Bash
/path/to/StoryForge/scripts/bootstrap_project.sh

# PowerShell
/path/to/StoryForge/scripts/bootstrap_project.ps1

This creates .claude/ (project config with delivery rules, hooks, skills, and rules) and .kanban/ (delivery artifacts).

3. Start working

1. Open Claude Code in your project
2. Claude reads the board automatically (SessionStart hook)
3. Use /story-write to plan your first story
4. Implement within the story scope
5. Use /doc-update when done

Dashboard

StoryForge includes a terminal dashboard that renders your Kanban state at a glance.

python scripts/dashboard.py

══════════════════════════════════════════════════════════════════════
                  STORYFORGE DASHBOARD — MyProject
══════════════════════════════════════════════════════════════════════

  KANBAN BOARD

    ○ Backlog     ◉ Ready     ▶ In Progress    ◈ Review     ✓ Done
                                █                            ████
        2            1            1               0            4

  Progress: ████████████████████████████████░░░░░░░░░░░░░░░░ 50% (4/8)

  FEATURES
    FEAT-001  Authentication System      [Done]
    FEAT-002  API Rate Limiting          [In Progress]

  ACTIVE STORIES
    ▶ STORY-005: Add rate limiter middleware
      Criteria: ██████████░░░░░░░░░░ 2/4 (50%)

  SPRINT
    Sprint 3 — API Hardening
    Stories: 4 total, 2 done, 1 in progress, 1 remaining
    Burndown: ██████████████████████░░░░░░░░ 50%

• Python 3.8+ (stdlib only, zero dependencies)
• ANSI colors with graceful fallback
• Works on Windows, macOS, and Linux

Web UI

For a visual board, StoryForge also includes a local web interface:

python scripts/kanban_webui.py

Opens a browser with an interactive Kanban board featuring:

• Board view — 5 columns (Backlog, Ready, In Progress, Review, Done) with story cards
• Features view — grid of all features grouped by initiative
• Backlog view — future work items
• Story modals — click any card to see details, acceptance criteria, and progress
• JSON API — available at /api/board for integrations

Dark theme, zero dependencies, runs on http://127.0.0.1:8742.

Cross-Platform

Every script ships in both Bash and PowerShell:

Script	Bash	PowerShell
Install global config	install_storyforge.sh	install_storyforge.ps1
Bootstrap a project	bootstrap_project.sh	bootstrap_project.ps1
Validate templates	validate_templates.sh	validate_templates.ps1
Sync upstream docs	sync_upstream_docs.sh	sync_upstream_docs.ps1
Kanban dashboard	dashboard.py	dashboard.py
Kanban web UI	kanban_webui.py	kanban_webui.py
Security audit	security_audit.py	security_audit.py
Upstream monitor	upstream_monitor.py	upstream_monitor.py
Release validation	validate_release.py	validate_release.py

Source of Truth Policy

StoryForge clearly separates what comes from Anthropic and what it adds on top:

Classification	Meaning	Example
Native	Officially supported by Claude Code	CLAUDE.md loading, hooks, agent frontmatter, permissions
Convention	StoryForge pattern layered on native primitives	Kanban board, story templates, agile workflow rules
Enforcement	Native mechanism used for guarantees	Permission deny rules, hook-based validators

CLAUDE.md guidance is contextual. Settings and permissions are enforcement. Hooks are lifecycle automation. Kanban discipline is a StoryForge convention.

These categories are never blurred.

See anthropic-source-map.md for the full mapping.

Documentation

Document	Purpose
Architecture	System design, layers, agent strategy, data flow
Operating Model	Work hierarchy, Kanban states, done criteria, anti-drift rules
Source of Truth Policy	Authority levels, classification system
Anthropic Source Map	Every capability mapped to its official Anthropic source
Upstream Doc Index	15 Anthropic doc pages with verification dates
Release Watch	Upstream change tracking and impact classification
Adaptation Process	How StoryForge adapts to Claude Code updates

Project Structure

storyforge/
  .claude/                    # StoryForge's own project config
    CLAUDE.md                 # Project-specific rules
    rules/                    # Path-specific rules (templates, docs, scripts)
  assets/                     # Banner and visual assets
  docs/                       # Architecture, policies, upstream tracking
  templates/
    home/.claude/             # Global layer (~/.claude/) — thin
      agents/                 # 8 agent definitions
      skills/                 # 4 global skills
      CLAUDE.md               # Identity + anti-drift (~27 lines)
      settings.json           # Security deny rules + PreToolUse guardrails
    project/                  # Project layer — rich
      .claude/                # Delivery rules, hooks, skills, rules
        skills/               # 5 project skills
        rules/                # kanban.md, storyforge-delivery.md
        CLAUDE.md             # Full delivery rules
        settings.json         # All hooks + deny rules
      .kanban/                # Kanban artifact templates
  scripts/                    # Bash + PowerShell + Python tooling
  tests/                      # 265 pytest tests
  examples/                   # Sample project with populated .kanban/

Validation

# Run the full test suite
python -m pytest tests/ -v

# Run the template validation script
bash scripts/validate_templates.sh     # or .\scripts\validate_templates.ps1

Changelog

See CHANGELOG.md for a history of major updates.

License

MIT

---

_{Built with discipline on Claude Code}