Nix Workflow Framework

Every project in projects/ SHOULD have a consistent directory layout with four key files.

projects/{name}/
├── PROJECT.md       # Vision, scope, stack, constraints
├── ROADMAP.md       # Phases with dependencies and status
├── STATE.md         # Current position, decisions, blockers
├── docs/            # Analysis, specs, diagrams
└── ...code...

# {Project Name}
## Vision: One-line description
## Stack: Languages, frameworks, hosting
## Constraints: Budget, hosting limits, timeline
## Scope v1: What's included
## Scope v2: What's deferred
## Links: Repo, production URL, Notion

# Roadmap
## Phase 1: {Name} [✅ DONE | 🔄 IN PROGRESS | ⏳ TODO]
- Dependencies: none
- Tasks: ...
## Phase 2: {Name} [status]
- Dependencies: Phase 1
- Tasks: ...

# State — Last updated: {date}
## Current Phase: {N}
## Current Task: {description}
## Decisions Made: (list of key decisions with rationale)
## Blockers: (anything blocking progress)
## Next Action: (exactly what to do next)

Lessons from 4 dead sub-agents on Mar 2, 2026.

Required Flags

claude --dangerously-skip-permissions "Your task"

The PTY Bypass Warning Problem

Even with --dangerously-skip-permissions, Claude Code shows an interactive prompt in PTY:

WARNING: Claude Code running in Bypass Permissions mode
❯ 1. No, exit        ← DEFAULT SELECTED
  2. Yes, I accept

Proven Solution

After launching with pty:true background:true:

# 1. Wait 5s
process poll timeout:5000

# 2. Send Down + Enter SEPARATELY (not together)
process send-keys sessionId:XXX keys:["Down"]
process poll timeout:1000   # wait for cursor move
process send-keys sessionId:XXX keys:["Enter"]

# 3. Verify it started working
process poll timeout:10000  # look for "Reading" or "thinking"

Post-Launch Monitoring

When spawning sub-agents, use this XML structure for clarity and consistency.

<task type="auto">
  <name>{Clear task name}</name>
  <context>{What the agent needs to know — project state, prior decisions}</context>
  <files>{Specific files to read/modify}</files>
  <action>
    {Step-by-step instructions. Be explicit about:}
    - What to create/modify
    - What patterns to follow
    - What to avoid
  </action>
  <verify>
    {How to confirm it works:}
    - Command to run
    - Expected output
    - Edge cases to test
  </verify>
  <done>
    {Definition of done — what success looks like}
  </done>
  <commit>{Commit message format}</commit>
</task>

Before spawning multiple sub-agents, map dependencies and group into waves for parallel execution.

1. 1
   List all tasks needed for the phase
2. 2
   Map dependencies — which tasks depend on others?
3. 3
   Group into waves: independent tasks in parallel, dependent tasks after
4. 4
   Respect the 5-agent limit — max 5 concurrent sub-agents per session
5. 5
   Track in STATE.md — update after each wave completes

# Example dependency graph:
Wave 1 (parallel):   Backend models, Seed data script
Wave 2 (parallel):   API routes (needs models), Frontend pages
Wave 3 (sequential): Integration tests (needs everything)

After EVERY task/sub-agent completion, run the appropriate verification checklist.

When starting work on an existing codebase, run 4 parallel analyses before touching anything.

Execute EVERY time, BEFORE reporting success. No exceptions.

Checklist (in order)

What counts as "significant"

"If I wake up tomorrow with zero memory, would I know this happened?" — If NO, you forgot to document. Go back and do it.

Every significant decision should be recorded with context to survive future memory loss.

Store in STATE.md for project decisions, MEMORY.md for cross-project decisions.

Any reusable knowledge discovered during a task must be persisted — not just in session memory.

Decision tree after every debug/integration task

Knowledge Destination Map

How to Update an Existing Skill

# 1. View the current skill
chub get nixclawd/<name>

# 2. Edit SKILL.md — add finding in "Known Gotchas" section
edit ~/clawd/skills/<name>/SKILL.md

# 3. Bump revision in frontmatter (revision: N → N+1) and updated-on
# 4. Update date in registry.json
python3 -c "
import json
from datetime import date
r = json.load(open('/Users/macdenix/clawd/skills/registry.json'))
for s in r['skills']:
    if s['id'] == 'nixclawd/<name>':
        s['lastUpdated'] = str(date.today())
        break
json.dump(r, open('/Users/macdenix/clawd/skills/registry.json','w'), indent=2)
print('Registry updated')
"

# 5. Sync to ~/.claude/skills/ for future sessions
cp ~/clawd/skills/<name>/SKILL.md ~/.claude/skills/<name>/SKILL.md