RFC: Task Artifact Pipeline System

[mrsergeifrolov]

RFC: Task Artifact Pipeline System

Status: Draft / Request for Comments
Author: Sergei Frolov (@SergeiFrolov)
Date: 2026-01-18
Target Version: v4.3+

Summary

A unified Task Artifact Pipeline system that simplifies and standardizes working with SuperClaude Framework.

Primary goals:

• Unified workflow — clear entry point (/sc:pm) and structured progression through stages
• Cross-session continuity — resume tasks exactly where you left off
• Context preservation — artifacts persist between commands, no need to re-explain

Additional benefits:

• Three predefined workflow types (Hotfix, Standard, Feature)
• Manifest-based summaries for minimal context consumption
• Parallel sub-task execution with dependency tracking

---

User Flow

Problem: No Clear Entry Point

Currently, users can start with any command:

/sc:brainstorm "auth"     ← starts here?
/sc:design "auth"         ← or here?
/sc:implement "auth"      ← or here?

Issues:

• No consistent starting point
• Each command works in isolation
• No task tracking or context preservation
• User must remember what was done previously
• Cross-session continuity is lost

Solution: PM as Single Entry Point

Recommended: Start with /sc:pm to enable full pipeline features.

Note: Existing commands continue to work independently for backward compatibility. The pipeline system activates only when PM creates a task.

PM Agent:

1. Analyzes the request
2. Determines appropriate workflow (Hotfix/Standard/Feature)
3. Creates task folder with manifest
4. Guides user through the pipeline

# Starting new task
/sc:pm "implement user authentication"

# Resuming work (PM reads last task from .superclaude/tasks/)
/sc:pm

Command Execution

After PM creates a task, user executes each stage:

User: /sc:pm "implement auth system"
PM: Task 003 created. Workflow: Feature.
    → Next: /sc:brainstorm

User: /sc:brainstorm
PM: Brainstorm complete. Saved to 01_brainstorm.md
    → Next: /sc:design

User: /sc:design
PM: Design complete. Saved to 02_design.md
    → Next: /sc:workflow

User: /sc:workflow
PM: Workflow complete. Saved to 03_workflow.md
    → Next: /sc:spawn

User: /sc:spawn
PM: Created 3 sub-tasks. Saved to 04_spawn.md
    → Next: /sc:task (for sub-task 003a)

User: /sc:task
PM: Sub-task 003a complete.
    → Next: /sc:task (for sub-task 003b)
...

---

Problem Statement

Current State

Commands operate in isolation — no automatic context passing:

Command	Creates Artifact?	Reads Previous?
/sc:brainstorm	No	No
/sc:design	No	No
/sc:workflow	Yes (claudedocs/)	No
/sc:spawn	No	No
/sc:task	No	No

Result: Each command starts from scratch. Context lives only in conversation.

PM Agent Memory Limitations

Current PM Agent uses Serena MCP memory (key-value storage):

pm_context     → Complete PM state (single key)
current_plan   → What we're working on
last_session   → Previous session summary
next_actions   → What to do next

Problems for multi-task scenarios:

Limitation	Current State	Impact
No Task IDs	Single pm_context for everything	Cannot distinguish between tasks
No Task History	Only last_session stored	Older tasks lost
No Status Tracking	No explicit statuses	Unknown what's started/completed
Wave Mode	Conceptual only	No persistence between waves
Unstructured	Key-value pairs	Hard to query, no relationships

Example failure scenario:

Session 1: /sc:pm "implement auth" --wave
  → Wave 1: Database schema ✓
  → Wave 2: Backend API (in progress)
  → Session ends

Session 2: /sc:pm
  → PM reads pm_context
  → "Where did I stop? Wave 2? Which wave 2? What was wave 1?"
  → Wave context lost, user must re-explain

What this RFC solves:

Problem	Solution
No Task IDs	003_20250118_auth-system/ folder naming
No History	.superclaude/tasks/ contains all tasks
No Statuses	manifest.json with status: pending/in_progress/completed
Wave tracking	sub-tasks/003a_*/manifest.json per wave/sub-task
Unstructured	JSON manifests + markdown artifacts

Deprecation: --strategy wave

With Task Artifact Pipeline, the --wave flag becomes redundant and will be deprecated.

Wave concept is absorbed into the pipeline:

# Deprecated
/sc:pm "implement auth" --strategy wave

# Replacement (Feature workflow)
/sc:pm "implement auth"
  → /sc:workflow        # Creates phases (replaces "waves")
  → /sc:spawn           # Decomposes into tracked sub-tasks
  → /sc:task (each)     # Execute with full persistence

Wave Mode	Task Artifact Pipeline
Conceptual — no persistence	Full persistence via manifests
Lost between sessions	Resumable with status tracking
Manual wave tracking	Automatic via spawn → sub-tasks

Result: Single consistent approach for multi-phase work with built-in tracking and resumability.

---

Proposed Solution

1. PM Agent as Single Entry Point

PM Agent handles ALL user requests and determines workflow type:

User: /sc:pm "request"
           │
           ▼
┌─────────────────────────────────────┐
│           PM Agent                  │
│  (Always-active entry point)        │
├─────────────────────────────────────┤
│ 1. Analyze request                  │
│ 2. Determine workflow type          │
│ 3. Create task folder + manifest    │
│ 4. Guide user through pipeline      │
└─────────────────────────────────────┘
           │
           ▼
  User executes: brainstorm → design → task → test

2. Three Workflow Types

Workflow	Pipeline	Use Case
Hotfix	implement → test	Typo, small bug, config
Standard	brainstorm → design → task → test	Single-scope feature
Feature	brainstorm → design → workflow → spawn → task(s) → test	Multi-component feature

3. Directory Structure

.superclaude/
├── config.json
└── tasks/
    ├── 001_20250118_fix-typo/              # Hotfix
    │   ├── manifest.json
    │   ├── 05_task.log.md
    │   └── 06_test.md
    │
    ├── 002_20250118_user-api/              # Standard
    │   ├── manifest.json
    │   ├── 01_brainstorm.md
    │   ├── 02_design.md
    │   ├── 05_task.log.md
    │   └── 06_test.md
    │
    └── 003_20250118_auth-system/           # Feature
        ├── manifest.json                   # Parent manifest (small)
        ├── 01_brainstorm.md
        ├── 02_design.md
        ├── 03_workflow.md
        ├── 04_spawn.md
        ├── sub-tasks/
        │   ├── 003a_database/
        │   │   ├── manifest.json           # Sub-task manifest
        │   │   └── 05_task.log.md
        │   ├── 003b_backend/
        │   │   ├── manifest.json
        │   │   └── 05_task.log.md
        │   └── 003c_frontend/
        │       ├── manifest.json
        │       └── 05_task.log.md
        ├── 05_task.log.md                  # Parent summary
        └── 06_test.md

Important: .superclaude/ directory is added to .gitignore when PM initializes a project. Task artifacts are local working files, not committed to repository.

---

Context Efficiency Design

Manifest as Single Entry Point

Problem: Reading all artifacts every time is inefficient.

Solution: Manifest contains summaries. Full artifacts loaded only when needed.

Parent Task Manifest

{
  "task_id": "003",
  "title": "User Authentication System",
  "workflow": "feature",
  "status": "in_progress",
  "current_stage": "task",
  "created_at": "2025-01-18T14:30:00Z",

  "stages": {
    "brainstorm": {
      "status": "completed",
      "completed_at": "2025-01-18T14:45:00Z"
    },
    "design": {
      "status": "completed",
      "completed_at": "2025-01-18T15:30:00Z"
    },
    "workflow": {
      "status": "completed",
      "completed_at": "2025-01-18T16:00:00Z"
    },
    "spawn": {
      "status": "completed",
      "completed_at": "2025-01-18T16:15:00Z"
    },
    "task": {
      "status": "in_progress"
    },
    "test": {
      "status": "pending"
    }
  },

  "summaries": {
    "brainstorm": "JWT + OAuth, 5 user stories, session mgmt, password reset",
    "design": "3 components: AuthService, TokenManager, SessionStore. REST API.",
    "workflow": "4 phases: DB → API → UI → Tests",
    "spawn": "3 sub-tasks created"
  },

  "artifacts": {
    "brainstorm": "01_brainstorm.md",
    "design": "02_design.md",
    "workflow": "03_workflow.md",
    "spawn": "04_spawn.md",
    "task": "05_task.log.md",
    "test": "06_test.md"
  },

  "sub_tasks": [
    { "id": "003a", "title": "Database", "status": "completed", "depends_on": [] },
    { "id": "003b", "title": "Backend API", "status": "in_progress", "depends_on": ["003a"] },
    { "id": "003c", "title": "Frontend UI", "status": "pending", "depends_on": ["003b"] }
  ],

  "related_files": []
}

Sub-Task Manifest

Each sub-task has its own manifest in sub-tasks/003a_database/manifest.json:

{
  "task_id": "003a",
  "parent_id": "003",
  "title": "Database Schema",
  "workflow": "standard",
  "status": "completed",
  "created_at": "2025-01-18T16:15:00Z",
  "completed_at": "2025-01-18T17:00:00Z",

  "stages": {
    "task": {
      "status": "completed",
      "completed_at": "2025-01-18T17:00:00Z"
    }
  },

  "summary": "Created users, sessions, tokens tables with indexes",

  "artifacts": {
    "task": "05_task.log.md"
  },

  "related_files": [
    "src/db/migrations/001_auth_tables.sql",
    "src/db/schema.ts"
  ]
}

---

Status Tracking

Stage Statuses

Status	Meaning
pending	Not started yet
in_progress	Currently being worked on
completed	Finished successfully
skipped	Not applicable for this workflow
blocked	Waiting for dependencies (sub-tasks only)

How Status Updates

1. Command starts → stage becomes in_progress
2. Command completes → stage becomes completed, completed_at timestamp added
3. Next stage → becomes in_progress

Task Completion

When all stages complete:

{
  "status": "completed",
  "completed_at": "2025-01-18T18:30:00Z",
  "stages": {
    "brainstorm": { "status": "completed", ... },
    "design": { "status": "completed", ... },
    "task": { "status": "completed", ... },
    "test": { "status": "completed", ... }
  }
}

Sub-Task Completion Flow

For Feature workflow with sub-tasks:

1. spawn completes → creates sub-task folders with manifests
2. Each sub-task → user runs /sc:task, sub-task manifest updates
3. Sub-task completes → parent manifest sub_tasks[].status updates
4. All sub-tasks complete → parent stages.task.status becomes completed
5. Continue → user runs /sc:test

Parallel Execution

Sub-tasks with no dependencies (depends_on: []) can execute in parallel via Claude Code subagents.

Dependency graph example:

sub_tasks: [
  { "id": "003a", "title": "Database",    "depends_on": [] },        ← Can start immediately
  { "id": "003b", "title": "Backend API", "depends_on": ["003a"] },  ← Waits for 003a
  { "id": "003c", "title": "Frontend UI", "depends_on": ["003a"] },  ← Waits for 003a
  { "id": "003d", "title": "Integration",  "depends_on": ["003b", "003c"] }  ← Waits for both
]

Execution waves:
  Wave 1: [003a]           ← Sequential (single task)
  Wave 2: [003b, 003c]     ← Parallel (no mutual dependencies)
  Wave 3: [003d]           ← Sequential (depends on wave 2)

How PM orchestrates parallel execution:

User: /sc:task

PM actions:
1. Read manifest.json → find sub-tasks with depends_on satisfied
2. If multiple ready → spawn parallel subagents:
   - Task agent for 003b (Backend API)
   - Task agent for 003c (Frontend UI)
3. Each subagent:
   - Reads its sub-task manifest
   - Executes implementation
   - Updates sub-task manifest status → completed
4. PM monitors all subagents
5. When wave complete → check next dependencies → spawn next wave

Manifest updates during parallel execution:

{
  "sub_tasks": [
    { "id": "003a", "status": "completed", "depends_on": [] },
    { "id": "003b", "status": "in_progress", "depends_on": ["003a"] },  ← Agent 1
    { "id": "003c", "status": "in_progress", "depends_on": ["003a"] },  ← Agent 2
    { "id": "003d", "status": "blocked", "depends_on": ["003b", "003c"] }
  ]
}

Benefits:

• Faster execution for independent tasks
• Natural fit for Claude Code's Task tool (subagents)
• Clear dependency tracking prevents race conditions

---

Command File Requirements

What Each Command Reads

Command	Always Reads	Reads for Context	Creates/Updates
PM (entry)	manifest.json	—	Creates task folder + manifest
brainstorm	manifest.json	—	01_brainstorm.md
design	manifest.json	01_brainstorm.md	02_design.md
workflow	manifest.json	01_brainstorm.md + 02_design.md	03_workflow.md
spawn	manifest.json	02_design.md + 03_workflow.md	04_spawn.md + sub-tasks/
task (Feature)	manifest.json	02_design.md + 04_spawn.md	05_task.log.md
task (Standard)	manifest.json	01_brainstorm.md + 02_design.md	05_task.log.md
implement (Hotfix)	manifest.json	—	05_task.log.md
test	manifest.json	05_task.log.md	06_test.md

Why Each File is Needed

Command	Reads	Reason
design	brainstorm	Needs requirements + user stories for architecture
workflow	brainstorm + design	Needs full context: what (requirements) + how (architecture)
spawn	design + workflow	Needs architecture + plan to decompose into sub-tasks
task (Feature)	design + spawn	Needs architecture + sub-task definitions
task (Standard)	brainstorm + design	Needs requirements + architecture for implementation
test	task.log	Needs list of modified files to test

---

Workflow Diagrams

Hotfix Workflow

/sc:pm "fix typo" → Workflow: Hotfix
         │
         ▼
┌───────────┐   ┌──────┐
│ implement │ → │ test │
└───────────┘   └──────┘
     │              │
     ▼              ▼
 task.log.md    test.md

Standard Workflow

/sc:pm "add logout" → Workflow: Standard
         │
         ▼
┌────────────┐   ┌────────┐   ┌──────┐   ┌──────┐
│ brainstorm │ → │ design │ → │ task │ → │ test │
└────────────┘   └────────┘   └──────┘   └──────┘

Feature Workflow

/sc:pm "implement auth" → Workflow: Feature
         │
         ▼
┌────────────┐   ┌────────┐   ┌──────────┐   ┌───────┐
│ brainstorm │ → │ design │ → │ workflow │ → │ spawn │
└────────────┘   └────────┘   └──────────┘   └───────┘
                                                  │
                    ┌─────────────────────────────┘
                    ▼
              ┌───────────┐
              │ sub-tasks │  Each has own manifest
              ├───────────┤
              │ task (a)  │ → 003a/manifest.json
              │ task (b)  │ → 003b/manifest.json
              │ task (c)  │ → 003c/manifest.json
              └───────────┘
                    │
                    ▼ (all sub-tasks complete)
              ┌──────┐
              │ test │
              └──────┘

---

Serena Integration

┌─────────────────────────────────────────┐
│            SERENA (.serena/)            │
│  Project-level, cross-task knowledge    │
├─────────────────────────────────────────┤
│  • Architecture patterns                │
│  • Team conventions                     │
│  • Historical decisions                 │
│  • Cross-task learnings                 │
└─────────────────────────────────────────┘
                    ▲
                    │ PM reads at session start
                    │ PM writes learnings after task complete
                    ▼
┌─────────────────────────────────────────┐
│      .superclaude/tasks/                │
│  Task-level artifacts                   │
├─────────────────────────────────────────┤
│  • This task's requirements             │
│  • This task's design                   │
│  • This task's progress                 │
└─────────────────────────────────────────┘

---

PM Agent Behavior

New Task

User: /sc:pm "implement payment processing"

PM actions:
1. Analyze request → Workflow: Feature
2. Get next task number (e.g., 007)
3. Create folder: .superclaude/tasks/007_20250118_payment-processing/
4. Create manifest.json with workflow type
5. Response: "Task 007 created. Workflow: Feature. → Next: /sc:brainstorm"

Resume Session

User: /sc:pm

PM actions:
1. Scan .superclaude/tasks/ for status: in_progress
2. Find: 003_auth-system (stage: task, sub-task 003b in_progress)
3. Read manifest summary
4. Response: "Resuming task 003: Auth System
              Progress: brainstorm ✓ → design ✓ → workflow ✓ → spawn ✓ → task [1/3]
              Current: Sub-task 003b (Backend API)
              → Next: /sc:task"

Orchestration Architecture

Q: Who computes waves and dependencies?
→ PM Agent reads manifest.json, computes which sub-tasks have depends_on satisfied.

Q: Who spawns subagents?
→ PM Agent uses Claude Code's Task tool to spawn parallel subagents.

Q: Where does PM run?
→ PM runs in the main conversation (user's terminal). Subagents run in background.

Q: Does PM have enough context?
→ Yes. PM reads only manifest.json (small, contains summaries). Subagents read full artifacts when needed.

Architecture diagram:

┌─────────────────────────────────────────────────────┐
│         User's Terminal (Main Conversation)         │
│  ┌───────────────────────────────────────────────┐  │
│  │                  PM Agent                     │  │
│  │                                               │  │
│  │  1. Read manifest.json (lightweight)         │  │
│  │  2. Compute ready sub-tasks (depends_on=[])  │  │
│  │  3. Spawn subagents via Task tool            │  │
│  │  4. Monitor progress (read manifest updates) │  │
│  │  5. When wave done → compute next wave       │  │
│  └───────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘
                         │
                         │ Task tool (can be parallel)
                         ▼
    ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
    │ Subagent A  │  │ Subagent B  │  │ Subagent C  │
    │ (003a_db)   │  │ (003b_api)  │  │ (003c_ui)   │
    │             │  │             │  │             │
    │ Input:      │  │ Input:      │  │ Input:      │
    │ • manifest  │  │ • manifest  │  │ • manifest  │
    │ • design.md │  │ • design.md │  │ • design.md │
    │ • spawn.md  │  │ • spawn.md  │  │ • spawn.md  │
    │             │  │             │  │             │
    │ Output:     │  │ Output:     │  │ Output:     │
    │ • code      │  │ • code      │  │ • code      │
    │ • task.log  │  │ • task.log  │  │ • task.log  │
    │ • manifest  │  │ • manifest  │  │ • manifest  │
    │   (status)  │  │   (status)  │  │   (status)  │
    └─────────────┘  └─────────────┘  └─────────────┘

PM context efficiency:

What PM reads	Size	Purpose
manifest.json	~1KB	Task status, summaries, dependencies
Sub-task manifests	~0.5KB each	Status updates only

PM does NOT read full artifacts (design.md, brainstorm.md) — subagents do.

Execution flow:

User: /sc:task

PM:
1. Read manifest.json
2. Find: 003a=completed, 003b=pending(depends:003a✓), 003c=pending(depends:003a✓)
3. Both 003b and 003c are ready → spawn 2 parallel subagents
4. Wait for both to complete (monitor manifest updates)
5. Read manifest again: 003b=completed, 003c=completed
6. Find: 003d=pending(depends:003b✓,003c✓) → ready
7. Spawn subagent for 003d
8. 003d completes → all sub-tasks done
9. Update parent manifest: stages.task.status = "completed"
10. Response: "All sub-tasks complete. → Next: /sc:test"

How Task tool parallelism works:

PM launches multiple Tasks in a single message — Claude Code executes them in parallel at API level (not Python threading):

PM message with 2 Task calls:
  ├── Task(subagent_type="task", prompt="Execute 003b Backend API")  ──┐
  │                                                                    │ API-level
  └── Task(subagent_type="task", prompt="Execute 003c Frontend UI")  ──┘ parallel
                         │
                         ▼
              Both run simultaneously
              (~4x faster than sequential)
                         │
                         ▼
              Both return results to PM
                         │
                         ▼
              PM reads updated manifests
              PM computes next wave

PM does NOT busy-wait. When Tasks complete, PM receives their results and continues.

Subagent isolation:

• Each subagent has its own context (reads its sub-task manifest + artifacts)
• Subagents write to different files (003b/task.log.md vs 003c/task.log.md)
• No git conflicts because sub-tasks are scoped to different code areas
• If sub-tasks need same files → they must be sequential (via depends_on)

Execution Modes

Planning stages are always manual — they require user input and decisions:

• /sc:brainstorm — clarifying questions, requirements discovery
• /sc:design — architecture decisions, trade-offs
• /sc:workflow — phase planning, priorities
• /sc:spawn — sub-task decomposition, dependency definition

Task execution can be automatic — once planning is complete:

User: /sc:pm "implement auth"
PM: Task 003 created. → Next: /sc:brainstorm

User: /sc:brainstorm
PM: [asks clarifying questions, user answers]
PM: Complete. → Next: /sc:design

User: /sc:design
PM: [architecture decisions with user]
PM: Complete. → Next: /sc:workflow

User: /sc:workflow
PM: Complete. → Next: /sc:spawn

User: /sc:spawn
PM: Created 3 sub-tasks with dependencies. → Next: /sc:task

# HERE user can choose:

# Option A: Manual execution (one by one)
User: /sc:task
PM: Sub-task 003a complete. → Next: /sc:task
User: /sc:task
PM: Sub-task 003b complete. → Next: /sc:task
...

# Option B: Auto execution (all sub-tasks)
User: /sc:task --auto
PM: Executing all sub-tasks automatically...
    → 003a (Database) — running...
    → 003a complete
    → 003b (Backend) + 003c (Frontend) — running in parallel...
    → 003b complete
    → 003c complete
    All sub-tasks complete. → Next: /sc:test

Auto mode stops when:

• All sub-tasks complete ✓
• User confirmation needed (e.g., "This will delete 50 files. Continue?")
• Error requires decision
• Sub-task fails and needs review

This is NOT full autopilot — user still controls planning. Auto only executes what was already planned in spawn.

---

Stage Requirements by Workflow

Stage	Hotfix	Standard	Feature	Reads for Context	Creates
brainstorm	—	Required	Required	—	brainstorm.md
design	—	Required	Required	brainstorm	design.md
workflow	—	—	Required	brainstorm + design	workflow.md
spawn	—	—	Required	design + workflow	spawn.md + sub-tasks/
task	—	Required	Required	(see matrix above)	task.log.md
implement	Required	(via task)	(via task)	—	task.log.md
test	Required	Required	Required	task.log	test.md

---

Backward Compatibility

Guiding Principle

All existing commands continue to work exactly as before. The pipeline system is an opt-in enhancement that activates only when PM creates a task.

Compatibility Matrix

Scenario	Behavior	Breaking?
User runs /sc:brainstorm directly	Works as before (output in conversation)	❌ No
User runs /sc:design directly	Works as before (output in conversation)	❌ No
User runs /sc:implement directly	Works as before (modifies code)	❌ No
User runs /sc:workflow directly	Creates claudedocs/workflow_*.md (unchanged)	❌ No
User runs /sc:pm first, then commands	Pipeline mode: artifacts saved to .superclaude/tasks/	❌ No (opt-in)

Key Guarantees

1. No forced migration: Existing workflows continue without modification
2. Opt-in activation: Pipeline only activates via /sc:pm
3. Gitignore ready: .superclaude/ already in .gitignore (line 108)
4. Serena coexistence: Manifest system works alongside existing Serena memory
5. PDCA docs unchanged: docs/pdca/[feature]/ continues for committed documentation

/sc:workflow File Location

Current behavior preserved:

• Direct invocation: claudedocs/workflow_*.md (visible, committed)
• Via PM pipeline: .superclaude/tasks/NNN_*/03_workflow.md (local, gitignored)

Both locations serve different purposes — claudedocs/ for shareable plans, .superclaude/ for local working context.

Migration Path (Optional)

Users who want full pipeline features:

1. Start using /sc:pm for new tasks
2. Existing claudedocs/ files remain accessible
3. No migration of old files required

---

This RFC is open for community discussion.

[mrsergeifrolov]

I'd like to implement this RFC myself, if the maintainers and community approve the proposal.

At this stage, I'm looking for feedback and discussion on the design. If there are no major concerns, I'll take it into implementation.

Questions I'd especially like feedback on:

• Are the three workflow types (Hotfix/Standard/Feature) sufficient?
• Is the manifest schema reasonable?
• Any concerns about the parallel execution approach?
• Thoughts on deprecating --strategy wave?

[mrsergeifrolov]

@mithun50 please tag everyone related

[mithun50]

@NomenAK @kazukinakai @hyunjae-labs

[mithun50]

@mrsergeifrolov if you can you can start working on this.