looop

Claude Automated Development Toolkit - Decompose requirements documents, single files, or inline text into detailed task lists and automatically execute in l...

Security Scan

The skill's code largely matches its stated purpose (automating decomposition and execution via the local Claude CLI), but it contains several risky choices (explicitly bypassing Claude permission prompts, automatically committing/pushing to git, and logging full Claude CLI output) that are disproportionate and require caution.

Purpose & Capability

Name/description claim automated decomposition + execution using Claude — the code and SKILL.md request a local Claude CLI and git, and write into a project src directory. Requiring the Claude CLI and git is coherent. Note: the SKILL.md and run.py intentionally use '--dangerously-skip-permissions' and automatically commit/push changes, which is not strictly necessary for decomposition and execution and increases risk.

Instruction Scope

Runtime instructions and the code tell the agent to read project documents (paths), create a .looop directory in the user-supplied src, run the local 'claude' CLI with a generated prompt, save full Claude CLI stream JSON to per-task log files, update tasks.json, and perform git commits (and optional push). The use of --dangerously-skip-permissions (in both SKILL.md and run.py's claude invocation) bypasses interactive permission checks. Logging the complete Claude CLI output (logger.claude) means any sensitive output Claude emits will be stored in project logs. Automatic commits/pushes mean generated changes can be written to and potentially pushed from the user's repo without additional confirmation.

Install Mechanism

No install spec; this is an instruction-plus-code skill that uses local binaries (claude, git). No downloads or archive extraction are present in the package, so the install risk is low.

Credentials

The skill declares no required environment variables or external credentials, and the code does not request unrelated secrets. It does copy the process environment into the subprocess env when invoking Claude and conditionally sets CLAUDE_CODE_GIT_BASH_PATH on Windows after probing the system. While no direct credential requests exist, the skill will run commands that may access the user's git credentials (for commit/push) and will log full Claude output, which could include secrets — this behavior is disproportionate for unattended operation.

Persistence & Privilege

always:false (normal). The skill is user-invocable and can be invoked autonomously (platform default). Combined with its behaviors (permission bypass, automatic git commits/pushes, and comprehensive logging), autonomous invocation increases the blast radius — a cautionary combination even though autonomous invocation alone is expected.

What to consider before installing

This skill appears to do what it claims (automate decomposition and run tasks via a local Claude CLI), but it takes several risky shortcuts: it runs Claude with --dangerously-skip-permissions, automatically commits (and can push) changes to your git repo, and writes the full Claude CLI output into per-task logs. Before installing or running it: (1) review the code yourself or run it in an isolated/test repository (not your main work repo); (2) never use the --push option on a repo you care about until you’ve inspected the produced commits; (3) inspect the .looop logs for sensitive output and consider removing or encrypting logs if they may contain secrets; (4) prefer running with interactive permission checks enabled (remove --dangerously-skip-permissions) or run the claude-cli commands manually first; (5) if you lack confidence, run the skill inside a throwaway VM or container and audit all changes it makes to the filesystem and git history.

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

Parameter	Required When	Description
--docs <DIR>	Decomposing requirements directory	Requirements document directory path
--doc <FILE>	Decomposing single doc file	Single requirements document file path
--requirement <TEXT>	Decomposing inline requirement	Direct requirement text string
--src <DIR>	Always required	Code 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:

File	Path	Description
tasks.json	<src_dir>/.looop/tasks.json	Task list data
progress.txt	<src_dir>/.looop/progress.txt	Task progress records
*.log	<src_dir>/.looop/*.log	Task execution logs

Log Files

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

Filename Pattern	When Created
Task_#0_Decompose_YYYY-MM-DD_HH-MM-SS.log	Requirements decomposition
Task_#N_TaskName_YYYY-MM-DD_HH-MM-SS.log	Each 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.

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

Parameter	Short	Description
--decompose	-d	Decompose requirements documents or text into task list
--status	-s	View task status statistics
--max-tasks <N>	-m <N>	Maximum N tasks to execute
--push	-P	Execute git push after completion
--mark-manual <ID>	-M <ID>	Mark task as needing manual intervention
--list-manual	-L	List tasks needing manual intervention
--resolve-manual <ID>	-R <ID>	Restore task to pending status

Usage Examples

# 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

{
  "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:

Field	Description
id	Unique task identifier
name	Concise imperative name (e.g. 'Create user model')
description	Detailed technical description with what/how/why/scope
priority	high (essential), medium (important), low (optional)
dependencies	Array of task IDs that must complete first
task_type	setup, core, feature, refactor, test, docs
estimated_files	Expected files to be created/modified
acceptance_criteria	Specific verifiable completion criteria
status	pending, 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

Status	Description
pending	Pending execution
in_progress	Currently executing
completed	Completed
blocked	Blocked
needs_manual	Needs 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