@houseofwolvesllc/claude-scrum-skill 1.5.0 → 1.6.0

package/README.md

@@ -1,57 +1,73 @@
 # 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. Includes project scaffolding, sprint planning, status tracking, sprint releases, full-project emulation testing, autonomous orchestration, and project cleanup. One PR per sprint, or let Claude drive the entire lifecycle hands-free.
+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 → GitHub Project with sprints, stories, branches
-                              ↓
-                        /sprint-plan → populate the next sprint
-                              ↓
-                     Claude works stories → auto-merge to release branch
-                              ↓
-                       /sprint-status → check progress anytime
-                              ↓
-                      /sprint-release → wrap up sprint, open release PR
-                              ↓
-                     You review one PR → merge to development
-                              ↓
-                        /sprint-plan → next cycle
+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 (scaffolds PRD if given, else uses existing board)
-                              ↓
-              ┌──────── Epic Completion Loop ────────┐
-              │  /sprint-plan → execute stories      │
-              │  → /sprint-release → merge to dev    │
-              │  → branch cleanup → next sprint      │
-              │  (repeat until all epics done)        │
-              └──────────────┬───────────────────────┘
-                              ↓
-              ┌──── Emulation Hardening Loop ────────┐
-              │  /project-emulate → parse findings   │
-              │  → generate PRD → /project-scaffold  │
-              │  → fix sprints → re-emulate          │
-              │  (repeat until clean)                 │
-              └──────────────┬───────────────────────┘
-                              ↓
-                     Production-ready codebase
+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](#installation)
+- [Configuration](#configuration)
+- [Quick Start](#quick-start)
+- [Provider Setup](#provider-setup)
+- [Skills Reference](#skills-reference)
+- [Branch Strategy](#branch-strategy)
+- [Personas](#personas)
+- [Autonomous Orchestration](#autonomous-orchestration)
+- [Customization](#customization)
+- [Tips](#tips)
+- [License](#license)
+
+---
+
 ## Installation
 
 ### Claude Code Plugin (recommended)
 
-Add the marketplace and install the plugin directly from GitHub:
-
 ```
 /plugin marketplace add houseofwolvesllc/claudescrumskill
 /plugin install claude-scrum-skill@houseofwolvesllc
 ```
 
-This installs all seven skills as a native Claude Code plugin with automatic updates. To update later:
+This installs all skills as a native Claude Code plugin with automatic updates. To update later:
 
 ```
 /plugin marketplace update
@@ -60,311 +76,336 @@ This installs all seven skills as a native Claude Code plugin with automatic upd
 ### npm
 
 ```bash
-# Global — installs to ~/.claude/skills/ (all projects)
+# Global install — available in all projects
 npm install -g @houseofwolvesllc/claude-scrum-skill
 
-# Local — installs to <project>/.claude/skills/ (this project only)
+# Local install — this project only
 npm install @houseofwolvesllc/claude-scrum-skill
 ```
 
-Global install copies skills to `~/.claude/skills/` so they're available everywhere. Local install copies them to your project's `.claude/skills/` directory — useful for dev containers and CI where the home directory is ephemeral.
+Global install copies skills to `~/.claude/skills/`. Local install copies them to `<project>/.claude/skills/` and adds `.claude-scrum-skill` to your `.gitignore`.
 
 ### Manual
 
-Clone the repo and copy the `skills/` contents into `~/.claude/skills/` (global) or `your-repo/.claude/skills/` (per-project). All skill directories must be siblings — `sprint-plan`, `sprint-status`, and `sprint-release` reference `../project-scaffold/references/CONVENTIONS.md` via relative path.
-
-**Note:** After installing, restart Claude Code for the skills to become available.
+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.
 
-## Quick Start
+> **Note:** After installing, restart Claude Code for the skills to become available.
 
-### 1. Create a Fine-Grained GitHub Personal Access Token
+---
 
-These skills use `gh` for all GitHub operations. You need a fine-grained PAT scoped to the repos you want to manage.
+## Configuration
 
-**Step 1:** Go to [github.com/settings/personal-access-tokens](https://github.com/settings/personal-access-tokens) and click **Generate new token**.
+All configuration lives in `skills/shared/config.json`:
 
-**Step 2:** Fill in the token details:
-- **Token name** — Something descriptive like `claude-code-pm`
-- **Expiration** — Set a reasonable window (90 days is a good default)
-- **Resource owner** — Your account (or your org if the repos live there)
-- **Repository access** — Select **Only select repositories**, then pick the repos these skills will manage
+```json
+{
+  "scaffolding": "local",
+  "paths": {
+    "specs": ".claude-scrum-skill/specs",
+    "adr": ".claude-scrum-skill/adr",
+    "backlog": ".claude-scrum-skill/backlog"
+  },
+  "jira": {
+    "project_key": ""
+  },
+  "trello": {
+    "board_id": ""
+  }
+}
+```
 
-**Step 3:** Under **Permissions → Repository permissions**, grant:
+### Scaffolding Modes
 
-| Permission | Access | Why |
-|---|---|---|
-| Contents | Read & Write | Create branches, push commits |
-| Issues | Read & Write | Create and update stories on the project board |
-| Metadata | Read | Required by GitHub for all fine-grained PATs |
-| Pull requests | Read & Write | Open PRs for story branches and releases |
+| Mode | Description | Auth Required |
+|------|-------------|---------------|
+| `local` | File-based backlog in your project directory (default) | None |
+| `github` | GitHub Issues, Milestones, and Projects | `gh` CLI |
+| `jira` | Jira Cloud issues, epics, and sprints | Env vars |
+| `trello` | Trello boards, lists, and cards | Env vars |
 
-**Step 4:** Under **Permissions → Account permissions**, grant:
+### Configurable Paths
 
-| Permission | Access | Why |
-|---|---|---|
-| Projects | Read & Write | Create project boards, custom fields, and views |
+| Path | Default | Purpose |
+|------|---------|---------|
+| `paths.specs` | `.claude-scrum-skill/specs` | Spec documents from `/spec` |
+| `paths.adr` | `.claude-scrum-skill/adr` | Architecture Decision Records |
+| `paths.backlog` | `.claude-scrum-skill/backlog` | Local backlog files (local mode only) |
 
-**Step 5:** Click **Generate token** and copy it immediately — you won't see it again.
+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`.
 
-**Step 6:** Authenticate the GitHub CLI with your new token:
+---
 
-```bash
-echo "YOUR_TOKEN" | gh auth login --with-token
-```
+## Quick Start
 
-Verify it worked:
+### Local Mode (default — no setup required)
 
-```bash
-gh auth status
-```
+1. **Write a PRD** — Create a markdown file describing your project, epics, and stories.
 
-**Security tip:** Do not grant write access to your `main` branch via the token. Set up branch protection rules so merges to `main` always require your manual review. This is the gate that keeps you in control.
+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/`.
 
-### 2. Write a PRD
+3. **Plan a sprint:**
+   ```
+   /sprint-plan
+   ```
 
-Create a markdown file with your project requirements. The more structured, the better the scaffold. At minimum, include:
-- Project name and description
-- Epics or major bodies of work with clear boundaries
-- User stories or features per epic
-- Acceptance criteria for each story
+4. **Work stories** — Tell Claude to pick up `executor:claude` stories from the sprint.
 
-### 3. Scaffold the Project
+5. **Check progress:**
+   ```
+   /sprint-status
+   ```
 
-Open Claude Code in your repo and run:
+6. **Release the sprint:**
+   ```
+   /sprint-release
+   ```
 
-```
-/project-scaffold path/to/your-prd.md
-```
+7. **Or go fully autonomous:**
+   ```
+   /project-orchestrate path/to/prd.md
+   ```
 
-This creates:
-- A GitHub Project board with custom fields (Status, Sprint, Priority, Executor, Story Points)
-- Board views: Current Sprint, Claude Queue, My Tasks, Backlog, Epic Overview
-- Issues for every story, labeled with type, priority, executor, and `epic:<slug>`
-- Epics tracked two ways: `epic:*` labels for visibility + milestones for progress tracking
-- Release branches for each epic
-- Branch protection on main
+### Remote Mode (GitHub, Jira, or Trello)
 
-Already have an existing project? The skill detects it and offers to add stories to existing epics or create new ones — no need to scaffold from scratch every time.
+1. Set `"scaffolding"` in `config.json` to `"github"`, `"jira"`, or `"trello"`.
+2. Complete the [provider setup](#provider-setup) for your chosen provider.
+3. Follow the same workflow above — the skills automatically use the configured provider's API.
 
-### 4. Plan a Sprint
+---
 
-```
-/sprint-plan owner/repo
-```
+## Provider Setup
 
-The skill pulls stories from the backlog, assigns them to the next sprint iteration, and sets up the release branch. It respects your velocity target (default: 20 story points) and prioritizes by the Priority field.
+### GitHub
 
-### 5. Assign an Executor
+Create a fine-grained Personal Access Token:
 
-Three executor labels control who works each story:
+1. Go to [github.com/settings/personal-access-tokens](https://github.com/settings/personal-access-tokens) and generate a new token.
 
-| Label | Who | When |
-|---|---|---|
-| `executor:claude` | Claude Code | Clear implementation path, no human judgment needed |
-| `executor:human` | You | Business decisions, credentials, external approvals |
-| `executor:cowork` | Cowork agent | Research, drafting, web-based tasks |
+2. Grant these **repository permissions**:
 
-### 6. Hand Off to Claude Code
+   | Permission | Access | Why |
+   |---|---|---|
+   | Contents | Read & Write | Create branches, push commits |
+   | Issues | Read & Write | Create and update stories |
+   | Metadata | Read | Required by GitHub for all PATs |
+   | Pull requests | Read & Write | Open PRs for releases |
 
-In Claude Code, tell it to work the sprint:
+3. Grant this **account permission**:
 
-> "Pick up the current sprint. Work through all stories labeled executor:claude in priority order. For each story, create a feature branch off the release branch, implement, open a PR back to the release branch, and move the issue to Done."
+   | Permission | Access | Why |
+   |---|---|---|
+   | Projects | Read & Write | Create project boards and fields |
 
-Claude works autonomously — branching, committing, opening PRs with auto-merge to the release branch.
+4. Authenticate the CLI:
+   ```bash
+   echo "YOUR_TOKEN" | gh auth login --with-token
+   gh auth status
+   ```
 
-### 7. Check Progress
+> **Security tip:** Do not grant write access to `main`. Set up branch protection so merges to `main` always require your review.
 
-```
-/sprint-status owner/repo
-```
+### Jira
 
-Get a progress report: stories completed vs. remaining, burndown, blockers, and what Claude is working on.
+1. Generate an API token at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens).
 
-### 8. Release the Sprint
+2. Set environment variables:
+   ```bash
+   export JIRA_SITE="https://yourcompany.atlassian.net"
+   export JIRA_EMAIL="you@example.com"
+   export JIRA_API_TOKEN="your-api-token"
+   ```
 
-```
-/sprint-release owner/repo
-```
+3. Optionally set the project key in `config.json`:
+   ```json
+   {
+     "scaffolding": "jira",
+     "jira": {
+       "project_key": "MYPROJ"
+     }
+   }
+   ```
 
-This closes the sprint, opens a release PR from the release branch into `development`, and summarizes everything that shipped. You review one PR, merge it, and the sprint is done. When you're ready for production, promote `development` into `main`.
+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.
 
-### 9. Emulate the Project
+### Trello
 
-```
-/project-emulate
-```
+1. Get your API key from [trello.com/power-ups/admin](https://trello.com/power-ups/admin).
 
-Claude reads the entire codebase and runs a multi-phase validation:
+2. Generate a token by visiting:
+   ```
+   https://trello.com/1/authorize?expiration=never&scope=read,write&response_type=token&key=YOUR_API_KEY
+   ```
 
-1. **Discovery** — finds every role, action, and permission boundary
-2. **Integration seam validation** — checks that Docker, build tools, transpilers, IoC containers, config files, and service contracts are mutually consistent
-3. **Layer contract validation** — traces data through response helpers, middleware chains, IoC resolution, config stores, and error handlers to verify every layer agrees on data shapes
-4. **Cross-service payload validation** — verifies that request/response bodies, query parameters, headers, shared types, pagination contracts, and error shapes match across service boundaries
-5. **Full lifecycle walkthrough** — emulates each role executing each action from deployment through teardown
-6. **Coverage report** — permission matrix, categorized issues, and missing coverage
+3. Set environment variables:
+   ```bash
+   export TRELLO_API_KEY="your-api-key"
+   export TRELLO_TOKEN="your-token"
+   ```
 
-### 10. Orchestrate (Optional — Full Autonomy)
+4. Optionally set the board ID in `config.json`:
+   ```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.
 
-```
-# Scaffold a PRD and orchestrate only its epics/stories
-/project-orchestrate path/to/prd.md
+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.
 
-# Orchestrate all open epics/stories on an existing project
-/project-orchestrate owner/repo
+> **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.
 
-# Both — scaffold PRD into a specific repo, then orchestrate
-/project-orchestrate path/to/prd.md owner/repo
-```
+---
 
-Instead of manually invoking each skill at every step, let Claude drive the entire lifecycle autonomously. Pass a PRD to scaffold and execute just that work, or pass a repo to execute everything on the board. The orchestrator loops through sprint planning, story execution (parallel subagents for `executor:claude` stories), sprint release, merge to development, and branch cleanup — repeating until all in-scope epics are complete. Then it runs emulation hardening loops against the **entire codebase** (not just the new work): emulate, generate a findings PRD, scaffold a hardening epic, fix everything, and re-emulate until the codebase is clean.
+## Skills Reference
 
-Human/cowork stories are skipped (they roll over). Merges to `development` happen automatically. Merges to `main` still require your review. State is persisted to `.claude/orchestration-state.md` so progress survives session restarts.
+| Skill | Command | What 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-emulate` | Integration 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 |
 
-### 11. Clean Up the Codebase
+The `[owner/repo]` argument is only needed in GitHub mode. Jira, Trello, and local modes read from config.
 
-```
-# Report issues without fixing
-/project-cleanup
+---
 
-# Scope to a specific directory
-/project-cleanup src/
+## Branch Strategy
 
-# Auto-fix everything
-/project-cleanup --fix
+All modes share the same git branch strategy:
 
-# Report only, no fixes even if --fix is present
-/project-cleanup --report-only
+```
+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
 ```
 
-Verify codebase hygiene across five dimensions: zero build errors/warnings, zero lint errors/warnings, HATEOAS and architecture compliance, no dead or duplicated code, and all tests passing with at least 50% coverage. The skill detects your toolchain (TypeScript, Go, Rust, Python, etc.) automatically.
-
-In `--fix` mode, it resolves issues in dependency order — dead code removal first, then build errors, lint violations, architecture fixes, and finally test fixes and coverage improvement. All changes are documented in a `FIXES.md` report. Without `--fix`, it produces a full report to `.claude/reports/cleanup-report/` without modifying code.
-
-Reads your project's `CLAUDE.md` for overrides — project rules always win over default best practices.
+- **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
 
-### 12. Repeat (Manual Mode)
+---
 
-```
-/sprint-plan owner/repo
-```
+## Personas
 
-If you prefer manual control, start the next sprint. The cycle continues until the project is complete.
+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`.
 
-## How It Works
+| Persona | Assigned via | Behavior |
+|---|---|---|
+| `impl` (default) | No label needed | Standard implementation — write code, tests, open PR |
+| `ops` | `persona:ops` label or frontmatter | Ops/infra posture — idempotency, rollback, least privilege |
+| `research` | `persona:research` label or frontmatter | Research posture — output is a document (ADR/RFC), not code |
+| `review` | Automatic (release gate) | Reviews the release diff, reports findings by severity |
 
-### Branch Strategy
+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.
 
-```
-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 branches auto-merge into the release branch when CI passes. At sprint end, the release branch merges into `development` after your review. When you're ready to ship, `development` merges into `main`. Two approval gates: one per sprint, one for production.
+## Autonomous Orchestration
 
-### GitHub Project Board
+`/project-orchestrate` chains all skills into a fully autonomous pipeline.
 
-The scaffold creates a GitHub Project (the newer Projects experience, not classic project boards) with these custom fields:
+### Phase 1 — Epic Completion Loop
 
-| Field | Type | Purpose |
-|---|---|---|
-| Status | Single select | Workflow state: Backlog → Ready → In Progress → In Review → Done |
-| Sprint | Iteration (2-week) | Time-boxed sprint assignment |
-| Priority | Single select | P0-Critical through P3-Low |
-| Executor | Single select | Who works this: `claude`, `human`, or `cowork` |
-| Story Points | Number | Fibonacci estimation (1, 2, 3, 5, 8, 13) |
+1. Scaffolds the PRD (if provided) or reads existing backlog
+2. Plans sprints via `/sprint-plan`
+3. Executes `executor:claude` stories in parallel via subagents with persona routing
+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
 
-Epics are tracked two ways: `epic:*` labels give scrum teams the vocabulary they expect right on every issue, while native GitHub Milestones power the progress tracking (open/closed counts, % complete) behind the scenes. Both are set at issue creation time. You can filter by either on any project view.
+### Phase 2 — Emulation Hardening Loop
 
-**Board views** use GitHub's view system:
+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)
 
-- **Current Sprint** — Board layout, filtered to the active sprint, columns by Status
-- **Claude Queue** — Table layout, filtered to `Executor = claude` and `Status = Ready`, sorted by Priority
-- **My Tasks** — Table layout, filtered to `Executor = human`, grouped by Sprint
-- **Backlog** — Table layout, filtered to `Status = Backlog`, sorted by Priority
-- **Epic Overview** — Table layout, grouped by Milestone, with field sums on Story Points
+### Phase 3 — Project Cleanup
 
-You can also use **Slice by** on any field to quickly filter the current view from a side panel — useful for slicing a sprint view by Executor or Priority.
+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
 
-### Shared Conventions
+### State Persistence
 
-All skills reference a single `CONVENTIONS.md` file that defines labels, branch naming, custom fields, executor guidelines, and story point standards. Edit it once and every skill inherits the changes.
+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.
 
-Located at: `project-scaffold/references/CONVENTIONS.md`
+### Safety Boundaries
 
-## Skills Reference
+- 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`
 
-| Skill | Command | What It Does |
-|---|---|---|
-| `project-scaffold` | `/project-scaffold <prd-path>` | Full project setup from PRD, or add stories to an existing project |
-| `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, open release PR to development |
-| `project-emulate` | `/project-emulate` | Integration seams, layer contracts, cross-service payloads, and full lifecycle walkthrough |
-| `project-orchestrate` | `/project-orchestrate [prd-path] [owner/repo]` | Autonomous lifecycle driver — sprint loop + emulation hardening until done |
-| `project-cleanup` | `/project-cleanup [path] [--fix] [--report-only]` | Build, lint, HATEOAS, dead code, and test coverage verification/enforcement |
+---
 
 ## Customization
 
 ### Sprint Length
-Edit `CONVENTIONS.md` → "Sprint Cadence" section. Default is 2 weeks.
+Edit `shared/references/CONVENTIONS.md` > "Sprint Cadence". Default: 2 weeks.
 
 ### Velocity Target
-The `sprint-plan` skill asks for velocity or defaults to 20 story points. Adjust as you calibrate.
+`/sprint-plan` asks for velocity or defaults to 20 story points.
 
 ### Label Colors
-All label hex colors are defined in the `project-scaffold` skill. Modify to match your preferences.
+Defined in `project-scaffold/SKILL.md`. Modify to match your preferences.
 
 ### Executor Criteria
-Edit `CONVENTIONS.md` → "Executor Assignment Guidelines" to tune what gets assigned to Claude vs. you vs. Cowork.
+Edit `shared/references/CONVENTIONS.md` > "Executor Assignment Guidelines".
 
-### Adding Epics
-Epics map to your PRD structure. To add new epics later, run `/project-scaffold` with the new PRD — it detects the existing project and lets you add stories to existing epics or create new ones.
-
-## Autonomous Orchestration
+### Personas
+Edit `shared/references/PERSONAS.md` to add or modify persona preambles.
 
-The `/project-orchestrate` skill is a meta-orchestrator that chains all other skills into a fully autonomous pipeline. After scaffolding your project, run it once and Claude handles everything else.
+### 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.
 
-### What It Does
-
-**Phase 1 — Epic Completion Loop:**
-1. Detects open epics and presents an overview
-2. Plans sprints via `/sprint-plan`
-3. Executes `executor:claude` stories in parallel via subagents (skips human/cowork — they roll over)
-4. Releases via `/sprint-release`
-5. Merges the release PR to `development` (pre-authorized, no confirmation needed)
-6. Cleans up merged branches
-7. Repeats until all epics are complete
+### 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.
 
-**Phase 2 — Emulation Hardening Loop:**
-1. Runs `/project-emulate` to discover issues
-2. Generates a hardening PRD from critical/warning findings
-3. Scaffolds a "Hardening (Run N)" epic via `/project-scaffold`
-4. Executes the hardening sprint (same loop as Phase 1)
-5. Re-emulates — if new issues found, repeats; if clean, done
+---
 
-### State Persistence
+## Shared References
 
-Orchestration state is saved to `.claude/orchestration-state.md` (human-readable markdown). If Claude hits a usage cap or the session restarts, it picks up exactly where it left off. The state file tracks the current phase, epic, sprint, story status, and a running log.
+All skills reference shared configuration and standards from `skills/shared/`:
 
-### Safety Boundaries
+```
+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
+```
 
-- Merges to `development` are pre-authorized (standing auth)
-- Merges to `main` are **never** automatic — always requires your review
-- Failed stories are retried once, then marked blocked — they don't halt the pipeline
-- Merge conflicts pause orchestration and escalate to you
-- After 3 hardening runs without a clean emulation, Claude pauses and asks for guidance
+---
 
 ## Tips
 
-- **Chunk large epics** into multiple sprints for natural review gates. If an epic has 30 stories, split it into 2-3 sprints rather than one massive batch.
-- **Start small.** Scaffold a real but small project first to calibrate your conventions before relying on it for bigger work.
-- **Branch protection is your safety net.** The PAT should not have write access to main. Merges to main always go through your review.
-- **Run `/project-emulate` before releases** to catch integration seam failures, layer contract mismatches, cross-service payload drift, permission gaps, and dead code before shipping.
-- **Run `/project-cleanup --fix` after major changes** to enforce build/lint cleanliness, remove dead code, and ensure test coverage stays above 50%.
+- **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).
+
+---
 
 ## License