Gastown Migration Skill

This skill analyzes existing projects and structures them for Gastown — Steve Yegge's multi-agent workspace manager.

Overview

The migration process transforms a project into Gastown-compatible structure:

project/
├── .gt/
│   ├── memory/
│   │   ├── semantic.json      # Permanent facts (tech stack, constraints)
│   │   ├── episodic.json      # Decisions with TTL (~30 days)
│   │   └── procedural.json    # Learned patterns
│   ├── beads/
│   │   └── gt-*.json          # Individual work items
│   └── convoys/
│       └── convoy-*.json      # Bundled work assignments
└── [existing project files]

Commands

Phase 1: Analyze (Semantic Memory)

Discovery Procedure

Scan these locations in order:

1. •

   Package files (for tech stack detection)

   • •package.json — Node.js runtime, framework, dependencies
   • •Cargo.toml — Rust projects
   • •go.mod — Go projects
   • •requirements.txt, pyproject.toml — Python projects
   • •Gemfile — Ruby projects
2. •

   Configuration files (for service detection)

   • •.firebaserc, firebase.json — Firebase
   • •wrangler.toml — Cloudflare Workers
   • •vercel.json — Vercel deployment
   • •docker-compose.yml, Dockerfile — Containerization
   • •*.env.example — Environment variables hint
3. •

   Documentation (for project understanding)

   • •README.md — Project description, setup instructions
   • •docs/ — Architecture docs, ADRs, PRDs
   • •CONTRIBUTING.md — Development workflow
   • •CHANGELOG.md — Project history
4. •

   Source structure (for codebase understanding)

   • •src/, lib/, app/ — Main code directories
   • •tests/, __tests__/, spec/ — Test directories
   • •schemas/, migrations/ — Database schemas

Output: semantic.json

{
  "$schema": "semantic-memory-v1",
  "project": {
    "name": "my-app",
    "type": "web-application",
    "primary_language": "TypeScript",
    "description": "A task management app for teams"
  },
  "tech_stack": {
    "runtime": "Node.js 20",
    "framework": "Next.js 14",
    "database": "Neon PostgreSQL",
    "auth": "Firebase Auth",
    "deployment": "Vercel",
    "styling": "Tailwind CSS",
    "testing": "Vitest"
  },
  "personas": [
    {"name": "Team Lead", "needs": ["assign tasks", "track progress"]},
    {"name": "Developer", "needs": ["see my tasks", "update status"]}
  ],
  "constraints": [
    "Must support offline mode",
    "GDPR compliant data handling"
  ],
  "non_goals": [
    "Mobile native app (web-only for MVP)",
    "Enterprise SSO (future phase)"
  ],
  "evidence": {
    "last_scan": "2026-01-27T10:00:00Z",
    "files_analyzed": ["package.json", "README.md", "docs/PRD.md"]
  }
}

Phase 2: Beads (Work Items)

Extraction Sources

Scan for work items in:

1. •

   TODO comments in source code

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

   GitHub Issues (if .git exists)

   • •Open issues via gh issue list
   • •Labels map to bead type/priority
3. •

   PRD documents

   • •User stories with acceptance criteria
   • •Feature requirements
4. •

   Backlog files

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

   Existing roadmap outputs

   • •scopecraft/EPICS_AND_STORIES.md
   • •scopecraft/OPEN_QUESTIONS.md

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>

Example: gt-abc12, gt-xyz99, gt-m4n5p

Phase 3: Convoy (Work Bundles)

Convoy Creation Rules

1. •Size: 3-7 beads per convoy (optimal batch)
2. •Coherence: Related beads grouped together
3. •Dependencies: Respect bead dependency order
4. •Parallelization: Independent convoys can run concurrently

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
  }
}

Bundling Strategies

1. •By Epic: Group all beads from same epic
2. •By Dependency Chain: Group dependent beads sequentially
3. •By Skill: Group beads requiring similar expertise
4. •By Size: Combine small beads, isolate large ones

Quality Gates

Analyze Gates

Beads Gates

Convoy Gates

Validation

Run validation with:

# Python validator
python plugins/lisa-loops-memory/hooks/validate_gastown.py

# Check specific phase
python plugins/lisa-loops-memory/hooks/validate_gastown.py --phase analyze
python plugins/lisa-loops-memory/hooks/validate_gastown.py --phase beads
python plugins/lisa-loops-memory/hooks/validate_gastown.py --phase convoy

Integration with Gastown

After migration, 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

Examples

See examples/ directory for sample outputs:

• •examples/gastown/semantic.json
• •examples/gastown/beads/
• •examples/gastown/convoys/