johno/gastown
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat: Add polecat workflow quality levels (basic/shiny/chrome)

Browse Source 
Three pre-baked polecat workflows with increasing rigor:
- mol-polecat-basic: 3 steps, for trivial P4 fixes
- mol-polecat-shiny: 6 steps, standard quality with design/review
- mol-polecat-chrome: 16 steps, max rigor with strategic context reading,
  triple code review, and decomposed implementation phases

Added --quality (-q) flag to gt sling as shorthand:
  gt sling gt-abc gastown -q basic   # quick fix
  gt sling gt-abc gastown -q shiny   # standard
  gt sling gt-abc gastown -q chrome  # max rigor

Chrome explicitly requires reading ~/gt/docs/hop/CONTEXT.md and
~/gt/docs/PRIMING.md before design begins.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
2025-12-29 23:18:10 -08:00
parent f99b98d94c
commit 91236ea268
4 changed files with 697 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

89
.beads/formulas/mol-polecat-basic.formula.toml Normal file
View File

@@ -0,0 +1,89 @@
description = """
Minimal polecat workflow for trivial fixes.
Use this for P4 backlog items, typo fixes, and simple changes that don't
require design review or extensive testing. Just get it done.
## When to Use
- Typo fixes
- Simple config changes
- Obvious bug fixes
- Documentation updates
- P4 priority items
## When NOT to Use
- New features (use shiny or chrome)
- Security-related changes (use chrome)
- Complex refactoring (use shiny)
- Anything P1 or P0 (use chrome)
"""
formula = "mol-polecat-basic"
type = "workflow"
version = 1
[[steps]]
id = "preflight"
title = "Quick preflight check"
description = """
Fast initialization - just enough to start working.
```bash
gt prime # Load context
gt mol status # Check your hook
bd show {{issue}} # Understand the task
```
Verify you understand what needs to be done. If unclear, ask.
**Exit criteria:** You know what to do."""
[[steps]]
id = "implement"
title = "Implement {{feature}}"
needs = ["preflight"]
description = """
Just do it. Keep it simple.
1. Make the change
2. Test it works locally
3. Commit with clear message:
```bash
git add <files>
git commit -m "fix: <description> ({{issue}})"
```
Don't overthink. Don't gold-plate. Don't scope-creep.
**Exit criteria:** Change implemented and committed."""
[[steps]]
id = "postflight"
title = "Submit and signal done"
needs = ["implement"]
description = """
Push and signal completion.
```bash
# Quick test
go test ./... # Must pass
# Push
git push -u origin $(git branch --show-current)
# Close issue
bd close {{issue}} --reason "Fixed"
bd sync
# Signal done
gt done
```
**Exit criteria:** Witness takes over from here."""
[vars]
[vars.issue]
description = "The issue ID assigned to this polecat"
required = true
[vars.feature]
description = "Brief description of what's being fixed"

502
.beads/formulas/mol-polecat-chrome.formula.toml
View File

@@ -1,169 +1,453 @@
description = """
Polecat work with strategic context reading before design.
Maximum rigor polecat workflow with deep context and triple review.
Chrome is "shiny" (the standard workflow) with a strategic context step. Before
designing the implementation, the polecat reads organizational context documents
that contain vision, principles, and constraints.
Chrome is for critical work where quality is paramount. Every phase is
decomposed into checkable atoms. Reviews are done three times. Context
is explicitly loaded before design begins.
This ensures work aligns with strategic direction without embedding hardcoded
paths in the workflow. The context_docs variable allows each project/organization
to specify their own strategic documents.
## When to Use
- P0/P1 priority issues
- Security-sensitive changes
- Core architecture work
- Public API changes
- Anything that could break production
## Variables
| Variable | Source | Description |
|----------|--------|-------------|
| feature | cook-time | The feature being implemented |
| context_docs | cook-time | Comma-separated paths to strategic context docs |
## Use Cases
1. **Gas Town work**: Use defaults (hop/CONTEXT.md, PRIMING.md)
2. **External projects**: Override with project-specific docs
3. **Minimal context**: Pass empty string to skip context reading"""
## Phases
1. **Deep Context** - Read strategic docs before starting
2. **Design** - Draft, review, finalize
3. **Implement** - Scaffold, core, edge cases
4. **Test** - Write, run, review
5. **Triple Review** - Three passes over the code
6. **Final** - Docs, cleanup, submit
"""
formula = "mol-polecat-chrome"
type = "workflow"
version = 1
# =============================================================================
# PHASE 1: DEEP CONTEXT
# =============================================================================
[[steps]]
id = "preflight"
title = "Load basic context"
description = """
Standard initialization.
```bash
gt prime # Load role context
bd prime # Load beads context
gt mol status # Check your hook
bd show {{issue}} # Full issue details
gt mail inbox # Check for additional context
```
**Exit criteria:** Session initialized, issue understood."""
[[steps]]
id = "read-strategic-context"
title = "Read organizational context documents"
title = "Read strategic context documents"
needs = ["preflight"]
description = """
Read strategic context documents before designing your implementation.
CRITICAL: Read the strategic context before designing.
**Documents to read:**
{{context_docs}}
These documents contain the vision, principles, and architectural decisions
that should guide your implementation. Do not skip this step.
For each document path:
1. Read the file using your Read tool
2. Understand the strategic vision, principles, and constraints
3. Note any specific guidelines that apply to {{feature}}
**1. Read CONTEXT.md:**
```bash
cat ~/gt/docs/hop/CONTEXT.md
```
This contains:
- Strategic vision
- Design principles
- What we're building and why
These documents contain the organizational context that should guide your work:
- Architectural patterns and conventions
- Design principles and trade-offs
- Strategic goals and priorities
- Things to avoid or deprecate
**2. Read PRIMING.md:**
```bash
cat ~/gt/docs/PRIMING.md
```
This contains:
- Role taxonomy
- Agent responsibilities
- System architecture
**Why this matters:**
Good implementations align with organizational direction. Reading context first
prevents designs that conflict with strategic goals or violate conventions.
**3. Absorb and consider:**
- How does {{feature}} fit the strategic vision?
- What principles apply to this work?
- Are there architectural constraints to respect?
**If documents are not found:**
Some paths may not exist in your environment. This is fine - read what's
available and proceed. The goal is context, not completeness.
Take notes if helpful. This context shapes your design.
**Exit criteria:** You've read available context docs and understand the
strategic considerations relevant to {{feature}}."""
**Exit criteria:** You understand the strategic context and how it applies."""
# =============================================================================
# PHASE 2: DESIGN (Draft -> Review -> Finalize)
# =============================================================================
[[steps]]
id = "design"
title = "Design {{feature}}"
id = "design-draft"
title = "Draft design for {{feature}}"
needs = ["read-strategic-context"]
description = """
Think carefully about architecture before writing code.
Create an initial design based on strategic context.
**Consider with strategic context in mind:**
- How does this fit into the existing system?
- Does this align with the strategic direction you read?
- What are the edge cases?
- What could go wrong?
- Is there a simpler approach that still meets the goals?
Write a design document (can be comments, markdown, or mental model):
**Design principles:**
- Follow existing codebase conventions
- Keep it simple - avoid over-engineering
- Prefer composition over inheritance
- Design for the current need, not hypothetical futures
1. **Problem Statement**: What exactly are we solving?
2. **Approach**: How will we solve it?
3. **Files to Modify**: What code changes?
4. **Dependencies**: What does this depend on?
5. **Risks**: What could go wrong?
6. **Alternatives Considered**: What else could we do?
**Exit criteria:** You have a clear mental model of what you'll build and
how it fits the strategic direction."""
Be specific. Reference the strategic context where relevant.
**Exit criteria:** Draft design exists."""
[[steps]]
id = "implement"
title = "Implement {{feature}}"
needs = ["design"]
id = "design-review"
title = "Review your design"
needs = ["design-draft"]
description = """
Write the code for {{feature}}. Follow the design. Keep it simple. Don't gold-plate.
Step back and critically review your draft design.
**Working principles:**
- Follow existing codebase conventions
- Make atomic, focused commits
- Keep changes scoped to the assigned issue
- Don't add features beyond what was asked
Questions to ask:
- Does this align with the strategic vision from CONTEXT.md?
- Is this the simplest solution that works?
- Have I considered all edge cases?
- What would break if my assumptions are wrong?
- Is this consistent with existing patterns in the codebase?
- Would another engineer understand this approach?
Look for:
- Over-engineering
- Missing edge cases
- Inconsistency with existing code
- Scope creep beyond {{issue}}
Revise the design based on this review.
**Exit criteria:** Design reviewed and improved."""
[[steps]]
id = "design-finalize"
title = "Finalize design"
needs = ["design-review"]
description = """
Lock in the design before implementation.
Final checklist:
- [ ] Approach is clear and justified
- [ ] All files to modify are identified
- [ ] Risks are acknowledged
- [ ] Success criteria are defined
- [ ] Design is consistent with strategic context
If you're uncertain about anything, now is the time to ask Witness:
```bash
gt mail send <rig>/witness -s "Design review: {{issue}}" -m "..."
```
Once finalized, commit to this design. Don't redesign mid-implementation.
**Exit criteria:** Design is final, ready to implement."""
# =============================================================================
# PHASE 3: IMPLEMENT (Scaffold -> Core -> Edge Cases)
# =============================================================================
[[steps]]
id = "implement-scaffold"
title = "Scaffold the structure"
needs = ["design-finalize"]
description = """
Create the skeleton before filling in logic.
1. Create new files if needed
2. Add function signatures with TODO bodies
3. Set up imports and dependencies
4. Add test file stubs
**Commit frequently:**
```bash
git add <files>
git commit -m "<type>: <description>"
git commit -m "scaffold: structure for {{feature}} ({{issue}})"
```
**Exit criteria:** Implementation complete, all changes committed."""
This should compile/parse but not work yet.
**Exit criteria:** Structure exists, compiles, ready for core logic."""
[[steps]]
id = "review"
title = "Review implementation"
needs = ["implement"]
id = "implement-core"
title = "Implement core logic"
needs = ["implement-scaffold"]
description = """
Review your own changes before running tests.
Fill in the happy path - the main functionality.
**Check for:**
- Does it match the design?
- Does it align with strategic context you read?
- Are there obvious bugs?
- Is it readable and maintainable?
- Are there security concerns?
Focus on:
- Primary use case working correctly
- Clear, readable code
- Following existing patterns
**Fix issues found:** Don't just note them - fix them now.
Don't worry about edge cases yet. Get the core working first.
**Exit criteria:** Changes are clean, reviewed, and ready for testing."""
```bash
git add <files>
git commit -m "feat: core logic for {{feature}} ({{issue}})"
```
**Exit criteria:** Core functionality works for the happy path."""
[[steps]]
id = "test"
title = "Test {{feature}}"
needs = ["review"]
id = "implement-edge-cases"
title = "Handle edge cases"
needs = ["implement-core"]
description = """
Write and run tests. Unit tests for new code, integration tests if needed.
Now handle the edge cases identified in design.
**Steps:**
1. Run the full test suite
2. Fix any regressions
3. Add tests for new functionality
4. Verify edge cases are covered
For each edge case:
1. Add the handling code
2. Add a test for it
3. Verify it works
**Exit criteria:** All tests pass, new code has appropriate test coverage."""
Common edge cases:
- Empty/nil inputs
- Boundary conditions
- Error conditions
- Concurrent access (if applicable)
```bash
git add <files>
git commit -m "feat: edge case handling for {{feature}} ({{issue}})"
```
**Exit criteria:** All known edge cases handled."""
# =============================================================================
# PHASE 4: TEST (Write -> Run -> Review)
# =============================================================================
[[steps]]
id = "submit"
id = "test-write"
title = "Write comprehensive tests"
needs = ["implement-edge-cases"]
description = """
Write tests for all new code.
Test categories:
1. **Unit tests** - Test individual functions
2. **Integration tests** - Test component interaction
3. **Regression tests** - Prevent the bug from recurring
Coverage goals:
- Happy path tested
- Each edge case tested
- Error conditions tested
- Boundary conditions tested
```bash
git add *_test.go
git commit -m "test: add tests for {{feature}} ({{issue}})"
```
**Exit criteria:** Comprehensive test coverage for new code."""
[[steps]]
id = "test-run"
title = "Run full test suite"
needs = ["test-write"]
description = """
Run ALL tests, not just your new ones.
```bash
go test ./... # Full test suite
go build ./... # Build check
```
**ALL TESTS MUST PASS.**
If tests fail:
- Your code broke something: FIX IT
- Pre-existing failure: file bead, but still need green
Do not proceed until all tests pass.
**Exit criteria:** Full test suite passes."""
[[steps]]
id = "test-review"
title = "Review test coverage"
needs = ["test-run"]
description = """
Verify tests are actually meaningful.
Check each test:
- Does it test real behavior, not implementation details?
- Could a bug slip past this test?
- Are assertions specific enough?
Look for:
- Missing negative tests (what should NOT happen)
- Missing boundary tests
- Tests that always pass (useless)
- Tests that test mocks instead of real code
Add any missing tests.
**Exit criteria:** Tests are comprehensive and meaningful."""
# =============================================================================
# PHASE 5: TRIPLE REVIEW
# =============================================================================
[[steps]]
id = "code-review-1"
title = "Code review pass 1: Correctness"
needs = ["test-review"]
description = """
First review pass: Is the code CORRECT?
```bash
git diff origin/main...HEAD
```
Focus on:
- Logic errors
- Off-by-one bugs
- Null pointer risks
- Race conditions
- Resource leaks
- Error handling gaps
For each issue found: FIX IT, don't just note it.
**Exit criteria:** No correctness issues remain."""
[[steps]]
id = "code-review-2"
title = "Code review pass 2: Security"
needs = ["code-review-1"]
description = """
Second review pass: Is the code SECURE?
Review for OWASP Top 10:
- Injection (SQL, command, path)
- Broken authentication
- Sensitive data exposure
- XXE
- Broken access control
- Security misconfiguration
- XSS
- Insecure deserialization
- Using components with known vulnerabilities
- Insufficient logging
Also check:
- Secrets not hardcoded
- Input validation
- Output encoding
- Proper error messages (don't leak info)
**Exit criteria:** No security issues remain."""
[[steps]]
id = "code-review-3"
title = "Code review pass 3: Quality"
needs = ["code-review-2"]
description = """
Third review pass: Is the code QUALITY?
Check:
- Naming: Are names clear and consistent?
- Structure: Is code well-organized?
- Comments: Are complex parts explained?
- DRY: Is there unnecessary duplication?
- SOLID: Are principles followed?
- Patterns: Does it match codebase conventions?
- Cruft: Any debug code, TODOs, dead code?
The code should be something you're proud of.
**Exit criteria:** Code is clean, maintainable, follows conventions."""
# =============================================================================
# PHASE 6: FINAL
# =============================================================================
[[steps]]
id = "docs-update"
title = "Update documentation"
needs = ["code-review-3"]
description = """
Update any affected documentation.
Check:
- README if user-facing changes
- Code comments for complex logic
- API docs if interfaces changed
- CHANGELOG if applicable
```bash
git add docs/ *.md
git commit -m "docs: update for {{feature}} ({{issue}})"
```
**Exit criteria:** Documentation reflects the changes."""
[[steps]]
id = "final-check"
title = "Final pre-submit check"
needs = ["docs-update"]
description = """
One last verification before submit.
```bash
# Clean state
git status # Must be clean
git stash list # Must be empty
# Tests still pass
go test ./...
# Review commit history
git log --oneline origin/main..HEAD
# Review final diff
git diff origin/main...HEAD --stat
```
If anything is wrong, fix it before proceeding.
**Exit criteria:** Everything is perfect."""
[[steps]]
id = "postflight"
title = "Submit for merge"
needs = ["test"]
needs = ["final-check"]
description = """
Submit for merge. Final check before handoff.
Push and signal completion.
**Checklist:**
```bash
git status # Clean working tree
git diff # Review staged changes
git log --oneline # Check commit history
```
# Push branch
git push -u origin $(git branch --show-current)
**Submit:**
```bash
git push origin HEAD
```
# Close issue with summary
bd close {{issue}} --reason "Implemented with chrome workflow: {{feature}}"
bd sync
**Signal completion:**
```bash
# Signal done
gt done
```
**Exit criteria:** Branch pushed, ready for merge queue."""
Witness will verify, send to merge queue, and terminate your session.
**Exit criteria:** Witness takes over from here."""
[vars]
[vars.issue]
description = "The issue ID assigned to this polecat"
required = true
[vars.feature]
description = "The feature being implemented"
required = true
[vars.context_docs]
description = "Comma-separated paths to strategic context documents (e.g., '~/gt/docs/hop/CONTEXT.md,~/gt/docs/PRIMING.md')"
default = "~/gt/docs/hop/CONTEXT.md,~/gt/docs/PRIMING.md"

178
.beads/formulas/mol-polecat-shiny.formula.toml Normal file
View File

@@ -0,0 +1,178 @@
description = """
Standard quality polecat workflow with design and review phases.
Engineer in a Box - the canonical right way for most work. Design before you
code. Review before you ship. Test before you submit.
## When to Use
- P2/P3 features and bugs
- New functionality
- Refactoring work
- Any non-trivial change
## Phases
1. **Preflight** - Load context, understand assignment
2. **Design** - Think before you code
3. **Implement** - Write the code
4. **Review** - Self-review your changes
5. **Test** - Run tests, verify coverage
6. **Postflight** - Submit and signal done
"""
formula = "mol-polecat-shiny"
type = "workflow"
version = 1
[[steps]]
id = "preflight"
title = "Load context and verify assignment"
description = """
Initialize your session and understand your assignment.
```bash
gt prime # Load role context
bd prime # Load beads context
gt mol status # Check your hook
bd show {{issue}} # Full issue details
gt mail inbox # Check for additional context
```
Understand:
- What exactly needs to be done?
- What files are likely involved?
- Are there dependencies or blockers?
- What does "done" look like?
If blocked or unclear, mail Witness immediately.
**Exit criteria:** You understand the work and can begin."""
[[steps]]
id = "design"
title = "Design {{feature}}"
needs = ["preflight"]
description = """
Think carefully about architecture BEFORE writing code.
Consider:
- How does this fit into the existing system?
- What are the edge cases?
- What could go wrong?
- Is there a simpler approach?
- What existing patterns should you follow?
Write a brief design note (can be in your head or as a comment):
- Approach: <how you'll solve it>
- Files: <what you'll modify>
- Risks: <what might go wrong>
**Exit criteria:** You have a clear plan before touching code."""
[[steps]]
id = "implement"
title = "Implement {{feature}}"
needs = ["design"]
description = """
Write the code following your design.
Working principles:
- Follow existing codebase conventions
- Make atomic, focused commits
- Keep changes scoped to the assigned issue
- Don't gold-plate or scope-creep
```bash
# Commit frequently:
git add <files>
git commit -m "<type>: <description> ({{issue}})"
```
If you find unrelated bugs, file a bead - don't fix them in this branch.
**Exit criteria:** Implementation complete, all changes committed."""
[[steps]]
id = "review"
title = "Review implementation"
needs = ["implement"]
description = """
Self-review your changes before running tests.
```bash
git diff origin/main...HEAD # All changes vs main
git log --oneline origin/main..HEAD # All commits
```
Check for:
| Category | Look For |
|----------|----------|
| Bugs | Off-by-one, null handling, edge cases |
| Security | Injection, auth bypass, exposed secrets |
| Style | Naming, formatting, code organization |
| Completeness | Missing error handling, incomplete paths |
| Cruft | Debug prints, commented code, TODOs |
Fix issues found - don't just note them.
**Exit criteria:** Changes are clean and ready for testing."""
[[steps]]
id = "test"
title = "Test {{feature}}"
needs = ["review"]
description = """
Run tests and verify coverage.
```bash
go test ./... # Full test suite
```
**ALL TESTS MUST PASS.** Do not proceed with failures.
If tests fail:
- Read the failure carefully
- If your change caused it: fix it
- If pre-existing: file a bead, but you still need green tests
New features should have tests. Bug fixes should have regression tests.
```bash
# Build check
go build ./...
```
**Exit criteria:** All tests pass, new code has appropriate coverage."""
[[steps]]
id = "postflight"
title = "Submit for merge"
needs = ["test"]
description = """
Clean up and submit.
```bash
# Verify clean state
git status # Should be clean
git stash list # Should be empty
# Push branch
git push -u origin $(git branch --show-current)
# Close issue
bd close {{issue}} --reason "Implemented: {{feature}}"
bd sync
# Signal done
gt done
```
Witness will verify, send to merge queue, and terminate your session.
**Exit criteria:** Witness takes over from here."""
[vars]
[vars.issue]
description = "The issue ID assigned to this polecat"
required = true
[vars.feature]
description = "The feature being implemented"
required = true

37
internal/cmd/sling.go
View File

@@ -55,6 +55,11 @@ Formula-on-Bead (--on flag):
gt sling mol-review --on gt-abc # Apply formula to existing work
gt sling shiny --on gt-abc crew # Apply formula, sling to crew
Quality Levels (shorthand for polecat workflows):
gt sling gt-abc gastown --quality=basic # mol-polecat-basic (trivial fixes)
gt sling gt-abc gastown --quality=shiny # mol-polecat-shiny (standard)
gt sling gt-abc gastown --quality=chrome # mol-polecat-chrome (max rigor)
Compare:
gt hook <bead> # Just attach (no action)
gt sling <bead> # Attach + start now (keep context)
@@ -79,6 +84,7 @@ var (
slingMolecule string // --molecule: workflow to instantiate on the bead
slingForce bool // --force: force spawn even if polecat has unread mail
slingAccount string // --account: Claude Code account handle to use
slingQuality string // --quality: shorthand for polecat workflow (basic|shiny|chrome)
)
func init() {
@@ -95,6 +101,7 @@ func init() {
slingCmd.Flags().StringVar(&slingMolecule, "molecule", "", "Molecule workflow to instantiate on the bead")
slingCmd.Flags().BoolVar(&slingForce, "force", false, "Force spawn even if polecat has unread mail")
slingCmd.Flags().StringVar(&slingAccount, "account", "", "Claude Code account handle to use")
slingCmd.Flags().StringVarP(&slingQuality, "quality", "q", "", "Polecat workflow quality level (basic|shiny|chrome)")
rootCmd.AddCommand(slingCmd)
}
@@ -110,6 +117,22 @@ func runSling(cmd *cobra.Command, args []string) error {
return fmt.Errorf("--var cannot be used with --on (formula-on-bead mode doesn't support variables)")
}
// --quality is shorthand for formula-on-bead with polecat workflow
// Convert: gt sling gt-abc gastown --quality=shiny
// To: gt sling mol-polecat-shiny --on gt-abc gastown
if slingQuality != "" {
qualityFormula, err := qualityToFormula(slingQuality)
if err != nil {
return err
}
// The first arg should be the bead, and we wrap it with the formula
if slingOnTarget != "" {
return fmt.Errorf("--quality cannot be used with --on (both specify formula)")
}
slingOnTarget = args[0] // The bead becomes --on target
args[0] = qualityFormula // The formula becomes first arg
}
// Determine mode based on flags and argument types
var beadID string
var formulaName string
@@ -777,3 +800,17 @@ func agentIDToBeadID(agentID string) string {
return ""
}
}
// qualityToFormula converts a quality level to the corresponding polecat workflow formula.
func qualityToFormula(quality string) (string, error) {
switch strings.ToLower(quality) {
case "basic", "b":
return "mol-polecat-basic", nil
case "shiny", "s":
return "mol-polecat-shiny", nil
case "chrome", "c":
return "mol-polecat-chrome", nil
default:
return "", fmt.Errorf("invalid quality level '%s' (use: basic, shiny, or chrome)", quality)
}
}