Structure

Scan for work items in:

1. GitHub Issues (most authoritative)

   gh issue list --state open --json number,title,body,labels
   

2. PRD Documents

   • docs/*.md with user stories
   • docs/PRD*.md files

3. TODO Comments in Source Code

   • // TODO:, # TODO:, /* TODO */
   • // FIXME:, // HACK:, // XXX:

4. Existing Roadmap Outputs

   • scopecraft/EPICS_AND_STORIES.md (from Stage 2)
   • scopecraft/OPEN_QUESTIONS.md

5. Backlog Files

   • BACKLOG.md, TODO.md
   • docs/backlog/, docs/roadmap/

Bead Schema

{
  "$schema": "bead-v1",
  "id": "gt-abc12",
  "title": "Add user authentication",
  "type": "feature",
  "complexity": "L",
  "priority": "high",
  "status": "pending",
  "dependencies": [],
  "acceptance_criteria": [
    "User can sign up with email",
    "User can sign in with Google OAuth",
    "Session persists across page refresh"
  ],
  "evidence": {
    "source": "docs/PRD-auth.md",
    "line": 42,
    "extracted": "2026-01-27T10:00:00Z"
  },
  "metadata": {
    "epic": "User Management",
    "labels": ["auth", "security"]
  }
}

Bead Types

Complexity Estimates

ID Generation

Bead IDs follow Gastown convention: gt-<5-char-alphanumeric>

• Use lowercase letters and numbers only
• Examples: gt-abc12, gt-xyz99, gt-m4n5p

Generate unique IDs:

import random
import string
def generate_bead_id():
    chars = string.ascii_lowercase + string.digits
    return f"gt-{''.join(random.choices(chars, k=5))}"

Bead Quality Requirements

Every bead must have:

• Clear, actionable title
• At least 1 acceptance criterion
• Evidence linking to source file
• Valid complexity estimate (XS/S/M/L/XL)
• Unique ID in gt-xxxxx format

Part 2: Convoy Bundling

Convoy Creation Rules

Bundling Strategies

1. By Epic

   • Group all beads from same epic/feature area
   • Best for feature-focused sprints

2. By Dependency Chain

   • Chain dependent beads sequentially
   • Best for complex features with prerequisites

3. By Skill

   • Group beads requiring similar expertise
   • Best for specialist assignment

4. By Size

   • Combine small beads (XS/S) together
   • Isolate large beads (L/XL)
   • Best for balanced workloads

Convoy Schema

{
  "$schema": "convoy-v1",
  "id": "convoy-001",
  "name": "Authentication Sprint",
  "description": "Implement core user authentication features",
  "beads": ["gt-abc12", "gt-def34", "gt-ghi56"],
  "assigned_to": null,
  "status": "pending",
  "created": "2026-01-27T10:00:00Z",
  "metadata": {
    "epic": "User Management",
    "estimated_days": 5
  }
}

ID Generation

Convoy IDs: convoy- + 3-digit number

• Sequential numbering: convoy-001, convoy-002, etc.
• Pad with zeros for sorting

Convoy Quality Requirements

Every convoy must have:

• 3-7 beads (optimal batch size)
• Coherent theme (epic, skill, or dependency chain)
• All referenced beads exist in .gt/beads/
• Clear description of bundle purpose

Execution Procedure

Step 1: Create Directories

mkdir -p .gt/beads .gt/convoys

Step 2: Extract Beads

For each source:

1. Scan for work items
2. Extract title, description, criteria
3. Classify type and complexity
4. Generate unique ID
5. Link evidence to source
6. Write to .gt/beads/gt-xxxxx.json

Step 3: Bundle into Convoys

1. Group beads by chosen strategy
2. Ensure 3-7 beads per convoy
3. Verify all bead references exist
4. Generate convoy ID
5. Write to .gt/convoys/convoy-xxx.json

Step 4: Validate

python plugins/lisa/hooks/validate.py --stage structure

Quality Gates

Bead Gates

Convoy Gates

Integration with Gastown

After structure completes, Gastown Mayor can:

1. Read Memory: Load .gt/memory/semantic.json for project context
2. List Beads: Enumerate .gt/beads/*.json for available work
3. Assign Convoys: Create/assign convoys to Polecats
4. Track Progress: Update bead/convoy status as work completes

Status Transitions

Bead:   pending -> in_progress -> completed | blocked
Convoy: pending -> assigned -> in_progress -> completed

Templates

See templates/ directory for JSON templates:

• templates/bead.json - Bead template
• templates/convoy.json - Convoy template