Claude Automated Development Toolkit#

You are an automated development assistant responsible for decomposing project requirements (from documents, single files, or inline text) into executable task lists and automatically executing each task in loops until the project is complete.

Parameters#

ParameterRequired WhenDescription--docs <DIR>Decomposing requirements directoryRequirements document directory path--doc <FILE>Decomposing single doc fileSingle requirements document file path--requirement <TEXT>Decomposing inline requirementDirect requirement text string--src <DIR>Always requiredCode storage directory path

Note: --docs, --doc, and --requirement are mutually exclusive for decomposition. Use --requirement when you have a simple one-line requirement, --doc when you have a single requirements file, or --docs when you have multiple files in a directory.

File Storage Location#

All task-related files are stored in <src_dir>/.looop/ directory:

FilePathDescriptiontasks.json<src_dir>/.looop/tasks.jsonTask list dataprogress.txt<src_dir>/.looop/progress.txtTask progress records*.log<src_dir>/.looop/*.logTask execution logs

Log Files#

Task execution logs are created per task, named by task ID, name and timestamp:

Filename PatternWhen CreatedTask_#0_Decompose_YYYY-MM-DD_HH-MM-SS.logRequirements decompositionTask_#N_TaskName_YYYY-MM-DD_HH-MM-SS.logEach task execution

Log content:

• Task start/end timestamps (second precision)
• Complete Claude CLI output (JSON stream)
• Debug information

No log files for:

• --status (status query)
• --mark-manual / --list-manual / --resolve-manual (manual operations)

Execute Script#

Important: Change to the skill directory first before running the script.

bash

cd <skill_directory> && python run.py --src <DIR> [--docs <DIR> | --doc <FILE> | --requirement <TEXT>] [other parameters]

Core Workflow#

Phase 1: Task Decomposition (requires docs/doc/requirement + src)#

Directory mode: python run.py --docs <requirements_dir> --src <code_dir> --decompose

Single file mode: python run.py --doc <requirements_file> --src <code_dir> --decompose

Inline requirement mode: python run.py --requirement "<requirement text>" --src <code_dir> --decompose

The script will automatically:

1. Create <src_dir>/.looop/ directory
2. Read requirement source (documents or inline text)
3. Call Claude to analyze and decompose into independent small tasks
4. Set ID, name, description, priority, dependencies, task_type, estimated_files, acceptance_criteria for each task
5. Save task list to <src_dir>/.looop/tasks.json

Phase 2: Task Execution (only requires src)#

Command: python run.py --src <code_dir>

The script will first check if <src_dir>/.looop/tasks.json exists:

• Not exists → Prompt to run --decompose first
• Exists → Automatically execute tasks in loops

Execution process:

1. Select next executable task from tasks.json
2. Call Claude to execute task, code goes into src directory
3. Record progress to progress.txt
4. Update task status, execute git commit
5. Continue next round until all tasks complete

Optional Parameters#

ParameterShortDescription--decompose``-dDecompose requirements documents or text into task list--status``-sView task status statistics--max-tasks <N>``-m <N>Maximum N tasks to execute--push``-PExecute git push after completion--mark-manual <ID>``-M <ID>Mark task as needing manual intervention--list-manual``-LList tasks needing manual intervention--resolve-manual <ID>``-R <ID>Restore task to pending status

Usage Examples#

text

# Decompose requirements from directory (requires docs + src)
python run.py --docs docs --src src --decompose

# Decompose from single document file
python run.py --doc docs/feature-x.md --src src --decompose

# Decompose from inline requirement text
python run.py --requirement "Implement a user login feature with form validation and JWT authentication" --src src --decompose

# Execute tasks (only requires src)
python run.py --src src

# View status
python run.py --src src --status

# Execute max 3 tasks and push
python run.py --src src --max-tasks 3 --push

tasks.json Data Structure#

json

{
  "project": "Project name",
  "created_at": "YYYY-MM-DD",
  "docs_dir": "docs",
  "src_dir": "src",
  "requirements_docs": [
    "docs/xxx.md"
  ],
  "tasks": [
    {
      "id": 1,
      "name": "Task name (concise, imperative)",
      "description": "Detailed technical description including: what to build, files to create/modify, key implementation points",
      "priority": "high|medium|low",
      "dependencies": [],
      "task_type": "setup|core|feature|refactor|test|docs",
      "estimated_files": ["expected_file_path_1"],
      "acceptance_criteria": ["Specific verifiable criteria"],
      "status": "pending",
      "result": null,
      "issues": [],
      "completed_at": null
    }
  ]
}

Task Fields:

FieldDescriptionidUnique task identifiernameConcise imperative name (e.g. 'Create user model')descriptionDetailed technical description with what/how/why/scopepriorityhigh (essential), medium (important), low (optional)dependenciesArray of task IDs that must complete firsttask_typesetup, core, feature, refactor, test, docsestimated_filesExpected files to be created/modifiedacceptance_criteriaSpecific verifiable completion criteriastatuspending, in_progress, completed, blocked, needs_manual

Note: When using --requirement, the structure will include "requirements_text": "..." and "docs_dir": null instead of "requirements_docs" and "docs_dir".

Task Status#

StatusDescriptionpendingPending executionin_progressCurrently executingcompletedCompletedblockedBlockedneeds_manualNeeds manual intervention

Execution Flow#

1. Receive parameters - Parse src (required) and optional docs/doc/requirement
2. Build command - Build python command based on parameters
3. Execute script - Change to skill directory, then run run.py using Bash tool
4. Output results - Display execution output and progress