uc-taskmanager-claude-agent

<p align="center">
  <img src="https://img.shields.io/badge/Claude_Code-Subagents-6b5ce7?style=for-the-badge&logo=anthropic&logoColor=white" />
  <img src="https://img.shields.io/badge/Language_Agnostic-Any_Stack-27ae60?style=for-the-badge" />
  <img src="https://img.shields.io/badge/License-GPLv3-f5a623?style=for-the-badge" />
</p>

# uc-taskmanager

Requirements Analysis & Development 6-Agent Full Pipeline + DAG-Based Orchestration + Sliding Window Context Management

**Universal Claude Task Manager** — A WORK-PIPELINE Agent that executes SDD (Specification-Driven Development) for Claude Code.
It formalizes user requirements into specifications,
builds execution plans (WORK) from those specs,
decomposes them into small tasks (TASK) and analyzes dependency graphs (DAG),
then automatically executes TASKs sequentially or in parallel based on dependencies.

Available as an **npm CLI** (`uctm`). Install once, use `[]`-tagged requests to trigger automated multi-agent pipelines.

**[한국어 문서 (Korean)](README_KO.md)**

---

## Quick Start

### npm CLI

```bash
npm install -g uctm
cd your-project
uctm init --lang en   # English agents
uctm init --lang ko   # 한국어 에이전트 (Korean — npm only)
uctm init             # Interactive language selection
```

`uctm init` automatically configures Bash permissions for agents in `settings.local.json` and installs `.claude-plugin` and `skills/` resources. No prompts required — the pipeline runs immediately after init.

### Start Using

Once installed, start Claude Code and use pipeline tags:

```
claude
> [new-feature] Add a hello world feature
```

Since `uctm init` automatically sets up permissions, the pipeline runs without additional prompts. If you need to bypass permissions in a CI/isolated environment:

```bash
claude --dangerously-skip-permissions
```

> **Warning**: Only use bypass mode in isolated environments or when you trust the pipeline fully. See [Claude Code Permissions](https://code.claude.com/docs/en/permissions) for details.

The agents analyze your request, plan the work, and execute through isolated subagent pipelines.

---

## What Makes This Pipeline Different

### 1. Procedures Must Be Executed Properly and Recorded

* Rather than focusing on *writing better code* (like TDD or DDD), this agent focuses on **executing development procedures properly**.
* It systematizes the full pipeline: **Requirement (user) → Specification → WORK Plan → Per-TASK Execution Plan → Per-TASK Execution/Verification/Completion → Per-TASK Result Storage** (WORK PIPELINE)
* The result: end-to-end records from requirement to delivery, providing full traceability.

**How to work with this AI Agent:**

* **Start**: Give a prompt starting with `[]` to trigger the WORK-PIPELINE
```
[game-dev] Build a brick breaker game in HTML
```

* **Requirement Analysis**: The agent analyzes your requirement and asks for approval. Review `works/WORK-NN/Requirement.md` and type **"approve"** to proceed.
```
{Requirement specification content}
If you approve Requirement.md, I will call the Planner to create PLAN.md + TASK decomposition.
Let me know if you want to modify anything.
```

* **WORK Execution Plan**: The agent builds an execution plan and asks again. Review `works/WORK-NN/PLAN.md` and `TASK-NN.md`, then type **"approve"** to proceed.
```
WORK-31 Development Approval Request

  Project folder structure reorganization ~~~~~~~ / ########

  ┌─────────┬─────────────────────────┐
  │  Item   │        Details          │
  ├─────────┼─────────────────────────┤
  │ Mode    │ full                    │
  ├─────────┼─────────────────────────┤
  │ TASKs   │ 6 (TASK-00 ~ TASK-05)  │
  └─────────┴─────────────────────────┘

  DAG Structure

  TASK-00 (move agents/ en files → en/ subdirectory)
     ├─→ TASK-01 (~~~~~~~~~~~~) ─→ TASK-03 (#########)
     ├─→ TASK-02 (create plugin/) ─→ TASK-04 (????????)
     └─────────────────────────────────→ TASK-05 ($$$$$$$$$)

  - TASK-01/02 parallel, TASK-03/04 parallel, TASK-05 final integration
  - If approved, scheduler → builder → verifier → committer pipeline will execute.

  Proceed?
```
* Per-TASK: build → verify → commit repeats automatically for each TASK.
```
● TASK-05 committed. Updating PROGRESS.md and finalizing WORK-31.
```
* When TASKs complete, verify via `works/WORK-NN/TASK-NN_result.md` and actual testing.
```
  push, merge
```

**Want to rollback?** Type `WORK-NN rollback`. Commit hashes are stored in the files, so only that WORK's changes are reverted.

**Too much ceremony for a simple button rename?**
```
[WORK start] Change the submit button label to "Send" — auto
```
Add "auto" to skip all approval steps and run the entire process automatically.

### 2. Token Economy

I'm cost-conscious (honestly). So this agent applies four token-saving strategies:

**(1) Serena MCP for codebase analysis.**
The agent prioritizes [Serena MCP](https://github.com/oraios/serena) for code exploration — reading symbols instead of entire files. (Huge thanks to the Serena team.)

**(2) Three execution modes + spawn consolidation to minimize subagent overhead.** The WORK-PIPELINE has 6 agent stages running sequentially. For a single-TASK WORK, that's 6 subagent sessions — each consuming tokens just to boot up. Wasteful. So the specifier agent decides the execution mode based on complexity: **direct** mode uses only 3 agent calls (specifier → builder → verifier+committer), skipping planner and scheduler. On top of this, related agents are combined into a single spawn: specifier+planner run together, and verifier+committer run together — reducing total spawns by **~30%** (6 TASKs: 20 → 14 spawns). See [Three Execution Modes](#concept-three-execution-modes).

**(3) Structured XML communication.** Subagents can't nest — Main Claude orchestrates everything.
* When one agent finishes and the next agent starts, Main Claude sits in between, causing data to be transmitted twice. This communication is a blob of text —
* The receiving side has to parse it again. So we standardized the communication format as XML.
* Every bit helps.
* (This also made agent log monitoring much easier.) See [Structured Agent Communication](#structured-agent-communication).

**(4) Sliding Window Context Transfer.** Agent A finishes and tells B what it did. B finishes and tells C what A did plus what B did. But does C really need A's full details? So B passes its own work in full to C, and summarizes A's work. **One degree of separation = just a name and phone number** — you don't need to know their personality. If curious, just ask them directly. Testing shows ~20-30% token savings. See [Sliding Window Context Transfer](#sliding-window-context-transfer).

**"Why not skip agents entirely and do everything in one session?"** See [Context Isolation](#context-isolation). In long sessions, AI gradually loses coherence — like sudden memory loss mid-conversation. Strict context isolation prevents this and directly impacts output quality.

### 3. Dependency-Aware Parallel Execution

TASKs within a WORK have dependency management via DAG. Parallel execution only happens when TASKs have no mutual dependencies — meaning no source code conflicts from concurrent edits.

I've also built a **requirement management system** that integrates with this pipeline. It manages requirements per project. Queue up requirements before bed, and by morning they're all developed — your to-do list just shifts to *reviewing* instead of *coding*. WORKs execute in parallel across projects too (cross-project dependencies don't exist).

### What's Next

Currently designing a **RAG-based system** to store accumulated artifacts and query similar past requirements during specification analysis — for faster and more accurate requirement decomposition. (If enough data accumulates, who knows — maybe a fine-tuned LLM behind an MCP someday.)

> **Tip for prompting AI agents**: Think of it like SQL WHERE clause ordering (developers only). The first condition should narrow the dataset the mo

[truncated…]