PaperclipOrg
Claude Agent Skill · by Wshobson

Track Management

Handles the complete lifecycle of Conductor tracks, which are structured work units for features, bugs, and refactors. Creates spec.md files with functional req

Install
Terminal · npx
$npx skills add https://github.com/wshobson/agents --skill track-management
Works with Paperclip

How Track Management fits into a Paperclip company.

Track Management drops into any Paperclip agent that handles this kind of work. Assign it to a specialist inside a pre-configured PaperclipOrg company and the skill becomes available on every heartbeat — no prompt engineering, no tool wiring.

S
SaaS FactoryPaired

Pre-configured AI company — 18 agents, 18 skills, one-time purchase.

$27$59
Explore pack
Source file
SKILL.md593 lines
Expand
---name: track-managementdescription: Use this skill when creating, managing, or working with Conductor tracks - the logical work units for features, bugs, and refactors. Applies to spec.md, plan.md, and track lifecycle operations.version: 1.0.0--- # Track Management Guide for creating, managing, and completing Conductor tracks - the logical work units that organize features, bugs, and refactors through specification, planning, and implementation phases. ## When to Use This Skill - Creating new feature, bug, or refactor tracks- Writing or reviewing spec.md files- Creating or updating plan.md files- Managing track lifecycle from creation to completion- Understanding track status markers and conventions- Working with the tracks.md registry- Interpreting or updating track metadata ## Track Concept A track is a logical work unit that encapsulates a complete piece of work. Each track has: - A unique identifier- A specification defining requirements- A phased plan breaking work into tasks- Metadata tracking status and progress Tracks provide semantic organization for work, enabling: - Clear scope boundaries- Progress tracking- Git-aware operations (revert by track)- Team coordination ## Track Types ### feature New functionality or capabilities. Use for: - New user-facing features- New API endpoints- New integrations- Significant enhancements ### bug Defect fixes. Use for: - Incorrect behavior- Error conditions- Performance regressions- Security vulnerabilities ### chore Maintenance and housekeeping. Use for: - Dependency updates- Configuration changes- Documentation updates- Cleanup tasks ### refactor Code improvement without behavior change. Use for: - Code restructuring- Pattern adoption- Technical debt reduction- Performance optimization (same behavior, better performance) ## Track ID Format Track IDs follow the pattern: `{shortname}_{YYYYMMDD}` - **shortname**: 2-4 word kebab-case description (e.g., `user-auth`, `api-rate-limit`)- **YYYYMMDD**: Creation date in ISO format Examples: - `user-auth_20250115`- `fix-login-error_20250115`- `upgrade-deps_20250115`- `refactor-api-client_20250115` ## Track Lifecycle ### 1. Creation (newTrack) **Define Requirements** 1. Gather requirements through interactive Q&A2. Identify acceptance criteria3. Determine scope boundaries4. Identify dependencies **Generate Specification** 1. Create `spec.md` with structured requirements2. Document functional and non-functional requirements3. Define acceptance criteria4. List dependencies and constraints **Generate Plan** 1. Create `plan.md` with phased task breakdown2. Organize tasks into logical phases3. Add verification tasks after phases4. Estimate effort and complexity **Register Track** 1. Add entry to `tracks.md` registry2. Create track directory structure3. Generate `metadata.json`4. Create track `index.md` ### 2. Implementation **Execute Tasks** 1. Select next pending task from plan2. Mark task as in-progress3. Implement following workflow (TDD)4. Mark task complete with commit SHA **Update Status** 1. Update task markers in plan.md2. Record commit SHAs for traceability3. Update phase progress4. Update track status in tracks.md **Verify Progress** 1. Complete verification tasks2. Wait for checkpoint approval3. Record checkpoint commits ### 3. Completion **Sync Documentation** 1. Update product.md if features added2. Update tech-stack.md if dependencies changed3. Verify all acceptance criteria met **Archive or Delete** 1. Mark track as completed in tracks.md2. Record completion date3. Archive or retain track directory ## Specification (spec.md) Structure ```markdown# {Track Title} ## Overview Brief description of what this track accomplishes and why. ## Functional Requirements ### FR-1: {Requirement Name} Description of the functional requirement. - Acceptance: How to verify this requirement is met ### FR-2: {Requirement Name} ... ## Non-Functional Requirements ### NFR-1: {Requirement Name} Description of the non-functional requirement (performance, security, etc.) - Target: Specific measurable target- Verification: How to test ## Acceptance Criteria - [ ] Criterion 1: Specific, testable condition- [ ] Criterion 2: Specific, testable condition- [ ] Criterion 3: Specific, testable condition ## Scope ### In Scope - Explicitly included items- Features to implement- Components to modify ### Out of Scope - Explicitly excluded items- Future considerations- Related but separate work ## Dependencies ### Internal - Other tracks or components this depends on- Required context artifacts ### External - Third-party services or APIs- External dependencies ## Risks and Mitigations | Risk             | Impact          | Mitigation          || ---------------- | --------------- | ------------------- || Risk description | High/Medium/Low | Mitigation strategy | ## Open Questions - [ ] Question that needs resolution- [x] Resolved question - Answer``` ## Plan (plan.md) Structure ```markdown# Implementation Plan: {Track Title} Track ID: `{track-id}`Created: YYYY-MM-DDStatus: pending | in-progress | completed ## Overview Brief description of implementation approach. ## Phase 1: {Phase Name} ### Tasks - [ ] **Task 1.1**: Task description  - Sub-task or detail  - Sub-task or detail- [ ] **Task 1.2**: Task description- [ ] **Task 1.3**: Task description ### Verification - [ ] **Verify 1.1**: Verification step for phase ## Phase 2: {Phase Name} ### Tasks - [ ] **Task 2.1**: Task description- [ ] **Task 2.2**: Task description ### Verification - [ ] **Verify 2.1**: Verification step for phase ## Phase 3: Finalization ### Tasks - [ ] **Task 3.1**: Update documentation- [ ] **Task 3.2**: Final integration test ### Verification - [ ] **Verify 3.1**: All acceptance criteria met ## Checkpoints | Phase   | Checkpoint SHA | Date | Status  || ------- | -------------- | ---- | ------- || Phase 1 |                |      | pending || Phase 2 |                |      | pending || Phase 3 |                |      | pending |``` ## Status Marker Conventions Use consistent markers in plan.md: | Marker | Meaning     | Usage                       || ------ | ----------- | --------------------------- || `[ ]`  | Pending     | Task not started            || `[~]`  | In Progress | Currently being worked      || `[x]`  | Complete    | Task finished (include SHA) || `[-]`  | Skipped     | Intentionally not done      || `[!]`  | Blocked     | Waiting on dependency       | Example: ```markdown- [x] **Task 1.1**: Set up database schema `abc1234`- [~] **Task 1.2**: Implement user model- [ ] **Task 1.3**: Add validation logic- [!] **Task 1.4**: Integrate auth service (blocked: waiting for API key)- [-] **Task 1.5**: Legacy migration (skipped: not needed)``` ## Track Registry (tracks.md) Format ```markdown# Track Registry ## Active Tracks | Track ID                                         | Type    | Status      | Phase | Started    | Assignee   || ------------------------------------------------ | ------- | ----------- | ----- | ---------- | ---------- || [user-auth_20250115](tracks/user-auth_20250115/) | feature | in-progress | 2/3   | 2025-01-15 | @developer || [fix-login_20250114](tracks/fix-login_20250114/) | bug     | pending     | 0/2   | 2025-01-14 | -          | ## Completed Tracks | Track ID                                       | Type  | Completed  | Duration || ---------------------------------------------- | ----- | ---------- | -------- || [setup-ci_20250110](tracks/setup-ci_20250110/) | chore | 2025-01-12 | 2 days   | ## Archived Tracks | Track ID                                             | Reason     | Archived   || ---------------------------------------------------- | ---------- | ---------- || [old-feature_20241201](tracks/old-feature_20241201/) | Superseded | 2025-01-05 |``` ## Metadata (metadata.json) Fields ```json{  "id": "user-auth_20250115",  "title": "User Authentication System",  "type": "feature",  "status": "in-progress",  "priority": "high",  "created": "2025-01-15T10:30:00Z",  "updated": "2025-01-15T14:45:00Z",  "started": "2025-01-15T11:00:00Z",  "completed": null,  "assignee": "@developer",  "phases": {    "total": 3,    "current": 2,    "completed": 1  },  "tasks": {    "total": 12,    "completed": 5,    "in_progress": 1,    "pending": 6  },  "checkpoints": [    {      "phase": 1,      "sha": "abc1234",      "date": "2025-01-15T13:00:00Z"    }  ],  "dependencies": [],  "tags": ["auth", "security"]}``` ## Track Operations ### Creating a Track 1. Run `/conductor:new-track`2. Answer interactive questions3. Review generated spec.md4. Review generated plan.md5. Confirm track creation ### Starting Implementation 1. Read spec.md and plan.md2. Verify context artifacts are current3. Mark first task as `[~]`4. Begin TDD workflow ### Completing a Phase 1. Ensure all phase tasks are `[x]`2. Complete verification tasks3. Wait for checkpoint approval4. Record checkpoint SHA5. Proceed to next phase ### Completing a Track 1. Verify all phases complete2. Verify all acceptance criteria met3. Update product.md if needed4. Mark track completed in tracks.md5. Update metadata.json ### Reverting a Track 1. Run `/conductor:revert`2. Select track to revert3. Choose granularity (track/phase/task)4. Confirm revert operation5. Update status markers ## Handling Track Dependencies ### Identifying Dependencies During track creation, identify: - **Hard dependencies**: Must complete before this track can start- **Soft dependencies**: Can proceed in parallel but may affect integration- **External dependencies**: Third-party services, APIs, or team decisions ### Documenting Dependencies In spec.md, list dependencies with: - Dependency type (hard/soft/external)- Current status (available/pending/blocked)- Resolution path (what needs to happen) ### Managing Blocked Tracks When a track is blocked: 1. Mark blocked tasks with `[!]` and reason2. Update tracks.md status3. Document blocker in metadata.json4. Consider creating dependency track if needed ## Track Sizing Guidelines ### Right-Sized Tracks Aim for tracks that: - Complete in 1-5 days of work- Have 2-4 phases- Contain 8-20 tasks total- Deliver a coherent, testable unit ### Too Large Signs a track is too large: - More than 5 phases- More than 25 tasks- Multiple unrelated features- Estimated duration > 1 week Solution: Split into multiple tracks with clear boundaries. ### Too Small Signs a track is too small: - Single phase with 1-2 tasks- No meaningful verification needed- Could be a sub-task of another track- Less than a few hours of work Solution: Combine with related work or handle as part of existing track. ## Specification Quality Checklist Before finalizing spec.md, verify: ### Requirements Quality - [ ] Each requirement has clear acceptance criteria- [ ] Requirements are testable- [ ] Requirements are independent (can verify separately)- [ ] No ambiguous language ("should be fast" → "response < 200ms") ### Scope Clarity - [ ] In-scope items are specific- [ ] Out-of-scope items prevent scope creep- [ ] Boundaries are clear to implementer ### Dependencies Identified - [ ] All internal dependencies listed- [ ] External dependencies have owners/contacts- [ ] Dependency status is current ### Risks Addressed - [ ] Major risks identified- [ ] Impact assessment realistic- [ ] Mitigations are actionable ## Plan Quality Checklist Before starting implementation, verify plan.md: ### Task Quality - [ ] Tasks are atomic (one logical action)- [ ] Tasks are independently verifiable- [ ] Task descriptions are clear- [ ] Sub-tasks provide helpful detail ### Phase Organization - [ ] Phases group related tasks- [ ] Each phase delivers something testable- [ ] Verification tasks after each phase- [ ] Phases build on each other logically ### Completeness - [ ] All spec requirements have corresponding tasks- [ ] Documentation tasks included- [ ] Testing tasks included- [ ] Integration tasks included ## Common Track Patterns ### Feature Track Pattern ```Phase 1: Foundation- Data models- Database migrations- Basic API structure Phase 2: Core Logic- Business logic implementation- Input validation- Error handling Phase 3: Integration- UI integration- API documentation- End-to-end tests``` ### Bug Fix Track Pattern ```Phase 1: Reproduction- Write failing test capturing bug- Document reproduction steps Phase 2: Fix- Implement fix- Verify test passes- Check for regressions Phase 3: Verification- Manual verification- Update documentation if needed``` ### Refactor Track Pattern ```Phase 1: Preparation- Add characterization tests- Document current behavior Phase 2: Refactoring- Apply changes incrementally- Maintain green tests throughout Phase 3: Cleanup- Remove dead code- Update documentation``` ## Best Practices 1. **One track, one concern**: Keep tracks focused on a single logical change2. **Small phases**: Break work into phases of 3-5 tasks maximum3. **Verification after phases**: Always include verification tasks4. **Update markers immediately**: Mark task status as you work5. **Record SHAs**: Always note commit SHAs for completed tasks6. **Review specs before planning**: Ensure spec is complete before creating plan7. **Link dependencies**: Explicitly note track dependencies8. **Archive, don't delete**: Preserve completed tracks for reference9. **Size appropriately**: Keep tracks between 1-5 days of work10. **Clear acceptance criteria**: Every requirement must be testable