work-assist-agent

한국어 README

A Claude Code custom agent that automatically generates structured work plans and work reports, then registers behavioral instructions in CLAUDE.md so any working agent auto-tracks progress with real-time timestamps.

Why?

When working with Claude Code on multi-step projects, it's easy to lose track of what's been done, what's in progress, and what's next. This agent solves that by:

• Auto-generating structured plans from your requirements, broken into Phases and Steps
• Embedding behavioral instructions in CLAUDE.md so the working agent automatically updates the report after every step
• Tracking progress with real-time timestamps — start/completion times recorded automatically
• Logging errors, architecture decisions, and scope changes as they happen
• Auto-finalizing when all steps are done — fills summary, updates checklist, cleans up memory
• Organizing everything by date in YYYY-MM-DD/ directories for clean project history

Installation

# Install globally
npm install -g work-assist-agent
work-assist-agent init

# Or use npx (no global install)
npx work-assist-agent init

Uninstall

work-assist-agent remove

Usage

Primary: Tag the Agent

The recommended way is to tag @work-assist-agent directly in Claude Code with your requirements:

@work-assist-agent Build a REST API with JWT authentication using Spring Boot

The agent handles the entire setup automatically:

1. Creates a YYYY-MM-DD/ directory
2. Generates work-plan.md with Phases, Steps, and deliverables
3. Generates work-report.md with tracking tables and compliance rules
4. Registers Active Work Context + behavioral Instructions in CLAUDE.md
5. Reports setup complete and exits

Then the main Claude session (or any working agent) picks up from there. Because the Instructions are embedded in CLAUDE.md, the working agent automatically:

• Follows compliance rules
• Records start/completion timestamps for every step
• Logs errors, architecture decisions, and scope changes
• Finalizes the report and cleans up memory when all steps are done

Alternative: Slash Commands

Three slash commands are also available for manual control:

| Command | Purpose | |---------|---------| | /work-plan [requirements] | Same as tagging — generates plan, report, and CLAUDE.md memory | | /work-update [progress] | Manually update progress (usually unnecessary with auto-tracking) | | /work-done [summary] | Manually finalize work and clean up memory |

How It Works

@work-assist-agent "Build feature X"
  │
  ▼
THIS AGENT runs (sub-agent):
  1. Create YYYY-MM-DD/ directory
  2. Generate work-plan.md
  3. Generate work-report.md
  4. Register CLAUDE.md memory + behavioral instructions
  5. Report setup complete → sub-agent exits
  │
  ▼
Main Claude session resumes:
  ├── Reads CLAUDE.md → finds Active Work Context + Instructions
  ├── Reads work-report.md → confirms compliance rules
  ├── Starts working on Step 1-1
  │     ├── Records start timestamp → updates report
  │     ├── Does the actual coding/work
  │     ├── Records completion timestamp → updates report
  │     └── Logs decisions, errors, notes → updates report
  ├── Continues through all Steps automatically
  └── When ALL Steps done → auto-finalizes report + removes CLAUDE.md memory

Generated Files

work-plan.md

Structured implementation plan with:

• Project overview (goal, tech stack, key considerations)
• Phases and Steps with expected deliverables
• Deliverables checklist

work-report.md

Progress tracking report with 7 sections:

| Section | Purpose | |---------|---------| | 0. Project Metadata | Project info, timestamps, file paths | | 1. Compliance Rules | Enforced behavioral rules for the working agent | | 2. Implementation Steps | Step-by-step tracking with Started/Completed timestamps | | 3. Architecture Decisions | Key technical decisions with alternatives and rationale | | 4. Error & Fix Log | Errors encountered and how they were resolved | | 5. Key Implementation Notes | Per-phase implementation details, code snippets, config changes | | 6. Scope Changes | Requirements added, changed, removed, or deferred | | 7. Work Summary | Final summary with duration, counts, and notes |

CLAUDE.md Memory Block

The Active Work Context block registered in CLAUDE.md includes:

• Data: current project name, plan/report paths, current phase, last updated timestamp
• Instructions: 9 behavioral rules that control the working agent's behavior — this is the key mechanism that enables full automation

Slash Command Details

/work-update [progress]

Automatically detects the update type from keywords:

| Update Type | Trigger Keywords | Action | |-------------|-----------------|--------| | Task started | "started", "beginning", "starting Phase N-M" | Records start timestamp | | Task completed | "completed", "finished", "done Phase N-M" | Records completion timestamp | | Error occurred | "error", "bug", "failed", "exception" | Adds to Error & Fix Log | | Error fixed | "fixed", "resolved", "solved" | Updates Error & Fix Log with fix | | Architecture decision | "decided", "chose", "using X instead of Y" | Adds to Architecture Decisions | | Scope change | "added feature", "deferred", "removed", "new requirement" | Adds to Scope Changes | | Implementation note | "implemented", "code structure", "configuration" | Appends to Key Implementation Notes | | General note | (anything else) | Appends to Notes column |

/work-done [summary]

Finalizes the work session:

1. Fills in the Work Summary section (total duration, completed phases, remaining items, decision/error/scope counts)
2. Updates the deliverables checklist in work-plan.md ([ ] → [x])
3. Removes the entire Active Work Context block (including Instructions) from CLAUDE.md

What Gets Installed

The init command copies files to your Claude Code configuration directory:

~/.claude/
├── agents/
│   └── work-assist-agent.md      # Setup agent definition
└── commands/
    ├── work-plan.md              # /work-plan slash command
    ├── work-done.md              # /work-done slash command
    └── work-update.md            # /work-update slash command

These are standard Claude Code custom slash commands and custom agents. No background processes, no daemons, no runtime dependencies.

Compliance Rules

The generated work-report.md and CLAUDE.md Instructions enforce these rules:

1. Print and confirm compliance rules before starting any work
2. Record real-time timestamps (YYYY-MM-DD HH:MM:SS) for every start/completion
3. Use Context7 MCP to avoid deprecated libraries and patterns
4. Log all errors and fixes with timestamps immediately
5. Review previous work before starting the next task
6. Log architecture decisions with alternatives and rationale
7. Log scope changes with type, impact, and decision
8. Update project metadata after every report modification
9. Auto-finalize when all steps complete (fill summary, update checklist, remove memory)

Requirements

• Claude Code CLI installed
• Node.js >= 16.0.0

License

MIT