Parallel Coding Agents with tmux and Markdown Specs

Manuel Schipper has been running parallel coding agents with a lightweight setup using tmux, Markdown files, bash aliases, and six slash commands. These are vanilla agents without subagent profiles or orchestrators, using a role naming convention per tmux window: Planner (builds Markdown specs), Worker (implements from finished specs), and PM (backlog grooming and idea dumping).

Feature Design System

Most code writing happens from finished specs called Feature Designs (FDs). An FD is a Markdown file containing:

• The problem being solved
• All solutions considered with pros and cons for each
• The final solution with implementation plan including files to update
• Verification steps

After adopting this system, Schipper can work in parallel with 4-8 agents. Beyond 8 agents, decision quality suffers. The system was built manually in one project with 300+ specs, then ported to new projects using a /fd-init command that bootstraps the setup into any repository.

FD Tracking and Lifecycle

Each FD gets a numbered spec file (FD-001, FD-002...) tracked in an index across all FDs. Files live in docs/features/ and move through 8 stages:

• Planned: Identified, not yet designed
• Design: Actively designing the solution
• Open: Designed, ready for implementation
• In Progress: Currently being implemented
• Pending Verification: Code complete, awaiting runtime verification
• Complete: Verified working, ready to archive
• Deferred: Postponed indefinitely
• Closed: Won't do

Slash Commands

Six slash commands handle the full lifecycle:

• /fd-new: Create a new FD from an idea dump
• /fd-status: Show the index: what's active, pending verification, and done
• /fd-explore: Bootstrap a session: load architecture docs, dev guide, FD index
• /fd-deep: Launch 4 parallel Opus agents to explore a hard design problem
• /fd-verify: Proofread code, propose a verification plan, commit
• /fd-close: Archive the FD, update the index, update the changelog

Every commit ties back to its FD (e.g., "FD-049: Implement incremental index rebuild"). The changelog accumulates automatically as FDs complete.

FD File Example

FD-051: Multi-label document classification
Status: Open
Priority: Medium
Effort: Medium
Impact: Better recall for downstream filtering

Problem
Incoming documents get a single category label, but many span multiple topics. Downstream filters miss relevant docs because the classifier forces a single best-fit.
Solution
Replace single-label classification with multi-label:

Use an LLM to assign confidence scores per category.
Accept all labels above 0.90 confidence.
For ambiguous scores (0.50-0.90), run a second LLM pass with few-shot examples to confirm.
Store all labels with scores so downstream queries can threshold flexibly.

Files to Modify

src/classify/multi_label.py (new: LLM-based multi-label logic)
src/classify/prompts.py (new: few-shot templates for ambiguous cases)
sql/01_schema.sql (add document_labels table with scores)
sql/06_classify_job.sql (new: scheduled classification after ingestion)

Verification

Run classifier on staging document table
Verify no errors in operation log, run health checks
Spot-check: docs with known multi-topic content have expected labels
Run tests, confirm downstream filters respect confidence threshold

System Initialization

Running /fd-init in any repository:

• Infers project context from CLAUDE.md, package configs, and git log
• Creates directory structure (docs/features/, docs/features/archive/)
• Generates a FEATURE_INDEX.md customized to the project
• Creates an FD template
• Installs the six slash commands
• Appends FD lifecycle conventions to the project's CLAUDE.md

Files created include docs/features/FEATURE_INDEX.md (feature index), docs/features/TEMPLATE.md (FD file template), docs/features/archive/ (archive directory), CHANGELOG.md (Keep a Changelog format), and updates to CLAUDE.md with project conventions including FD system.