spec-runner 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. spec_runner-0.1.0/PKG-INFO +180 -0
  2. spec_runner-0.1.0/README.md +151 -0
  3. spec_runner-0.1.0/pyproject.toml +71 -0
  4. spec_runner-0.1.0/setup.cfg +4 -0
  5. spec_runner-0.1.0/src/spec_runner/__init__.py +65 -0
  6. spec_runner-0.1.0/src/spec_runner/executor.py +1862 -0
  7. spec_runner-0.1.0/src/spec_runner/py.typed +0 -0
  8. spec_runner-0.1.0/src/spec_runner/task.py +719 -0
  9. spec_runner-0.1.0/src/spec_runner.egg-info/PKG-INFO +180 -0
  10. spec_runner-0.1.0/src/spec_runner.egg-info/SOURCES.txt +12 -0
  11. spec_runner-0.1.0/src/spec_runner.egg-info/dependency_links.txt +1 -0
  12. spec_runner-0.1.0/src/spec_runner.egg-info/entry_points.txt +3 -0
  13. spec_runner-0.1.0/src/spec_runner.egg-info/requires.txt +8 -0
  14. spec_runner-0.1.0/src/spec_runner.egg-info/top_level.txt +1 -0
spec_runner-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,180 @@
1
+ Metadata-Version: 2.4
2
+ Name: spec-runner
3
+ Version: 0.1.0
4
+ Summary: Task automation from markdown specs via Claude CLI
5
+ Author: Andrei
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/pr0sto/spec-runner
8
+ Project-URL: Repository, https://github.com/pr0sto/spec-runner
9
+ Keywords: automation,tasks,claude,cli,specs,markdown
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Operating System :: POSIX :: Linux
15
+ Classifier: Operating System :: MacOS
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Topic :: Software Development :: Build Tools
20
+ Requires-Python: >=3.10
21
+ Description-Content-Type: text/markdown
22
+ Requires-Dist: PyYAML>=6.0
23
+ Provides-Extra: dev
24
+ Requires-Dist: pytest>=7.0; extra == "dev"
25
+ Requires-Dist: pytest-cov>=4.0; extra == "dev"
26
+ Requires-Dist: ruff>=0.1.0; extra == "dev"
27
+ Requires-Dist: mypy>=1.0; extra == "dev"
28
+ Requires-Dist: types-PyYAML; extra == "dev"
29
+
30
+ # spec-runner
31
+
32
+ Task automation from markdown specs via Claude CLI. Execute tasks from a structured `tasks.md` file with automatic retries, code review, and Git integration.
33
+
34
+ ## Installation
35
+
36
+ ```bash
37
+ pip install spec-runner
38
+ ```
39
+
40
+ Or for development:
41
+ ```bash
42
+ pip install -e ".[dev]"
43
+ ```
44
+
45
+ Requirements:
46
+ - Python 3.10+
47
+ - Claude CLI (`claude` command available)
48
+ - Git (for branch management)
49
+
50
+ ## Quick Start
51
+
52
+ ```bash
53
+ # Execute next ready task
54
+ spec-runner run
55
+
56
+ # Execute specific task
57
+ spec-runner run --task=TASK-001
58
+
59
+ # Execute all ready tasks
60
+ spec-runner run --all
61
+
62
+ # Create tasks interactively
63
+ spec-runner plan "add user authentication"
64
+ ```
65
+
66
+ ## Usage as Library
67
+
68
+ ```python
69
+ from spec_runner import Task, ExecutorConfig, parse_tasks, get_next_tasks
70
+ from pathlib import Path
71
+
72
+ tasks = parse_tasks(Path("spec/tasks.md"))
73
+ ready = get_next_tasks(tasks)
74
+
75
+ for task in ready:
76
+ print(f"{task.id}: {task.name} ({task.priority})")
77
+ ```
78
+
79
+ ## Features
80
+
81
+ - **Task-based execution** — reads tasks from `spec/tasks.md` with priorities, checklists, and dependencies
82
+ - **Specification traceability** — links tasks to requirements (REQ-XXX) and design (DESIGN-XXX)
83
+ - **Automatic retries** — configurable retry policy with error context passed to next attempt
84
+ - **Code review** — multi-agent review after task completion
85
+ - **Git integration** — automatic branch creation, commits, and merges
86
+ - **Progress logging** — timestamped progress file for monitoring
87
+ - **Interactive planning** — create tasks through dialogue with Claude
88
+
89
+ ## Task File Format
90
+
91
+ Tasks are defined in `spec/tasks.md`:
92
+
93
+ ```markdown
94
+ ## Milestone 1: MVP
95
+
96
+ ### TASK-001: Implement user login
97
+ 🔴 P0 | ⬜ TODO | Est: 2d
98
+
99
+ **Checklist:**
100
+ - [ ] Create login endpoint
101
+ - [ ] Add JWT token generation
102
+ - [ ] Write unit tests
103
+
104
+ **Depends on:** —
105
+ **Blocks:** [TASK-002], [TASK-003]
106
+ ```
107
+
108
+ ## CLI Commands
109
+
110
+ ### spec-runner
111
+
112
+ ```bash
113
+ spec-runner run # Execute next ready task
114
+ spec-runner run --task=TASK-001 # Execute specific task
115
+ spec-runner run --all # Execute all ready tasks
116
+ spec-runner status # Show execution status
117
+ spec-runner retry TASK-001 # Retry failed task
118
+ spec-runner logs TASK-001 # View task logs
119
+ spec-runner reset # Reset state
120
+ spec-runner plan "feature" # Interactive task creation
121
+ ```
122
+
123
+ ### spec-task
124
+
125
+ ```bash
126
+ spec-task list # List all tasks
127
+ spec-task list --status=todo # Filter by status
128
+ spec-task show TASK-001 # Task details
129
+ spec-task start TASK-001 # Mark as in_progress
130
+ spec-task done TASK-001 # Mark as done
131
+ spec-task stats # Statistics
132
+ spec-task next # Show next ready tasks
133
+ spec-task graph # Dependency graph
134
+ ```
135
+
136
+ ## Configuration
137
+
138
+ Configuration file: `executor.config.yaml`
139
+
140
+ ```yaml
141
+ executor:
142
+ max_retries: 3
143
+ task_timeout_minutes: 30
144
+ claude_command: "claude"
145
+
146
+ hooks:
147
+ pre_start:
148
+ create_git_branch: true
149
+ post_done:
150
+ run_tests: true
151
+ run_lint: true
152
+ auto_commit: true
153
+ run_review: true
154
+
155
+ commands:
156
+ test: "pytest tests/ -v"
157
+ lint: "ruff check ."
158
+ ```
159
+
160
+ ## Project Structure
161
+
162
+ ```
163
+ project/
164
+ ├── pyproject.toml
165
+ ├── executor.config.yaml
166
+ ├── src/
167
+ │ └── spec_runner/
168
+ │ ├── __init__.py
169
+ │ ├── executor.py
170
+ │ └── task.py
171
+ └── spec/
172
+ ├── tasks.md
173
+ ├── requirements.md
174
+ ├── design.md
175
+ └── prompts/
176
+ ```
177
+
178
+ ## License
179
+
180
+ MIT
spec_runner-0.1.0/README.md ADDED
@@ -0,0 +1,151 @@
1
+ # spec-runner
2
+
3
+ Task automation from markdown specs via Claude CLI. Execute tasks from a structured `tasks.md` file with automatic retries, code review, and Git integration.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ pip install spec-runner
9
+ ```
10
+
11
+ Or for development:
12
+ ```bash
13
+ pip install -e ".[dev]"
14
+ ```
15
+
16
+ Requirements:
17
+ - Python 3.10+
18
+ - Claude CLI (`claude` command available)
19
+ - Git (for branch management)
20
+
21
+ ## Quick Start
22
+
23
+ ```bash
24
+ # Execute next ready task
25
+ spec-runner run
26
+
27
+ # Execute specific task
28
+ spec-runner run --task=TASK-001
29
+
30
+ # Execute all ready tasks
31
+ spec-runner run --all
32
+
33
+ # Create tasks interactively
34
+ spec-runner plan "add user authentication"
35
+ ```
36
+
37
+ ## Usage as Library
38
+
39
+ ```python
40
+ from spec_runner import Task, ExecutorConfig, parse_tasks, get_next_tasks
41
+ from pathlib import Path
42
+
43
+ tasks = parse_tasks(Path("spec/tasks.md"))
44
+ ready = get_next_tasks(tasks)
45
+
46
+ for task in ready:
47
+ print(f"{task.id}: {task.name} ({task.priority})")
48
+ ```
49
+
50
+ ## Features
51
+
52
+ - **Task-based execution** — reads tasks from `spec/tasks.md` with priorities, checklists, and dependencies
53
+ - **Specification traceability** — links tasks to requirements (REQ-XXX) and design (DESIGN-XXX)
54
+ - **Automatic retries** — configurable retry policy with error context passed to next attempt
55
+ - **Code review** — multi-agent review after task completion
56
+ - **Git integration** — automatic branch creation, commits, and merges
57
+ - **Progress logging** — timestamped progress file for monitoring
58
+ - **Interactive planning** — create tasks through dialogue with Claude
59
+
60
+ ## Task File Format
61
+
62
+ Tasks are defined in `spec/tasks.md`:
63
+
64
+ ```markdown
65
+ ## Milestone 1: MVP
66
+
67
+ ### TASK-001: Implement user login
68
+ 🔴 P0 | ⬜ TODO | Est: 2d
69
+
70
+ **Checklist:**
71
+ - [ ] Create login endpoint
72
+ - [ ] Add JWT token generation
73
+ - [ ] Write unit tests
74
+
75
+ **Depends on:** —
76
+ **Blocks:** [TASK-002], [TASK-003]
77
+ ```
78
+
79
+ ## CLI Commands
80
+
81
+ ### spec-runner
82
+
83
+ ```bash
84
+ spec-runner run # Execute next ready task
85
+ spec-runner run --task=TASK-001 # Execute specific task
86
+ spec-runner run --all # Execute all ready tasks
87
+ spec-runner status # Show execution status
88
+ spec-runner retry TASK-001 # Retry failed task
89
+ spec-runner logs TASK-001 # View task logs
90
+ spec-runner reset # Reset state
91
+ spec-runner plan "feature" # Interactive task creation
92
+ ```
93
+
94
+ ### spec-task
95
+
96
+ ```bash
97
+ spec-task list # List all tasks
98
+ spec-task list --status=todo # Filter by status
99
+ spec-task show TASK-001 # Task details
100
+ spec-task start TASK-001 # Mark as in_progress
101
+ spec-task done TASK-001 # Mark as done
102
+ spec-task stats # Statistics
103
+ spec-task next # Show next ready tasks
104
+ spec-task graph # Dependency graph
105
+ ```
106
+
107
+ ## Configuration
108
+
109
+ Configuration file: `executor.config.yaml`
110
+
111
+ ```yaml
112
+ executor:
113
+ max_retries: 3
114
+ task_timeout_minutes: 30
115
+ claude_command: "claude"
116
+
117
+ hooks:
118
+ pre_start:
119
+ create_git_branch: true
120
+ post_done:
121
+ run_tests: true
122
+ run_lint: true
123
+ auto_commit: true
124
+ run_review: true
125
+
126
+ commands:
127
+ test: "pytest tests/ -v"
128
+ lint: "ruff check ."
129
+ ```
130
+
131
+ ## Project Structure
132
+
133
+ ```
134
+ project/
135
+ ├── pyproject.toml
136
+ ├── executor.config.yaml
137
+ ├── src/
138
+ │ └── spec_runner/
139
+ │ ├── __init__.py
140
+ │ ├── executor.py
141
+ │ └── task.py
142
+ └── spec/
143
+ ├── tasks.md
144
+ ├── requirements.md
145
+ ├── design.md
146
+ └── prompts/
147
+ ```
148
+
149
+ ## License
150
+
151
+ MIT
spec_runner-0.1.0/pyproject.toml ADDED
@@ -0,0 +1,71 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61.0"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "spec-runner"
7
+ version = "0.1.0"
8
+ description = "Task automation from markdown specs via Claude CLI"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = {text = "MIT"}
12
+ authors = [
13
+ {name = "Andrei"}
14
+ ]
15
+ keywords = ["automation", "tasks", "claude", "cli", "specs", "markdown"]
16
+ classifiers = [
17
+ "Development Status :: 3 - Alpha",
18
+ "Environment :: Console",
19
+ "Intended Audience :: Developers",
20
+ "License :: OSI Approved :: MIT License",
21
+ "Operating System :: POSIX :: Linux",
22
+ "Operating System :: MacOS",
23
+ "Programming Language :: Python :: 3.10",
24
+ "Programming Language :: Python :: 3.11",
25
+ "Programming Language :: Python :: 3.12",
26
+ "Topic :: Software Development :: Build Tools",
27
+ ]
28
+
29
+ dependencies = [
30
+ "PyYAML>=6.0",
31
+ ]
32
+
33
+ [project.optional-dependencies]
34
+ dev = [
35
+ "pytest>=7.0",
36
+ "pytest-cov>=4.0",
37
+ "ruff>=0.1.0",
38
+ "mypy>=1.0",
39
+ "types-PyYAML",
40
+ ]
41
+
42
+ [project.scripts]
43
+ spec-runner = "spec_runner.executor:main"
44
+ spec-task = "spec_runner.task:main"
45
+
46
+ [project.urls]
47
+ Homepage = "https://github.com/pr0sto/spec-runner"
48
+ Repository = "https://github.com/pr0sto/spec-runner"
49
+
50
+ [tool.setuptools.packages.find]
51
+ where = ["src"]
52
+
53
+ [tool.ruff]
54
+ line-length = 100
55
+ target-version = "py311"
56
+
57
+ [tool.ruff.lint]
58
+ select = ["E", "F", "W", "I", "UP", "B", "C4", "SIM"]
59
+ ignore = ["E501"]
60
+
61
+ [tool.mypy]
62
+ python_version = "3.11"
63
+ warn_return_any = true
64
+ warn_unused_configs = true
65
+ ignore_missing_imports = true
66
+
67
+ [tool.pytest.ini_options]
68
+ testpaths = ["tests"]
69
+ markers = [
70
+ "slow: marks tests as slow",
71
+ ]
spec_runner-0.1.0/setup.cfg ADDED
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
spec_runner-0.1.0/src/spec_runner/__init__.py ADDED
@@ -0,0 +1,65 @@
1
+ """
2
+ spec-runner — task automation from markdown specs via Claude CLI.
3
+
4
+ Usage as library:
5
+ from spec_runner import ExecutorConfig, Task
6
+ from spec_runner import parse_tasks, get_next_tasks
7
+
8
+ Usage as CLI:
9
+ spec-runner run # Execute next task
10
+ spec-runner run --all # Execute all ready tasks
11
+ spec-runner status # Execution status
12
+
13
+ spec-task list # List all tasks
14
+ spec-task next # Show next ready tasks
15
+ spec-task stats # Statistics
16
+ """
17
+
18
+ from .task import (
19
+ TASKS_FILE,
20
+ Task,
21
+ get_next_tasks,
22
+ get_task_by_id,
23
+ mark_all_checklist_done,
24
+ parse_tasks,
25
+ resolve_dependencies,
26
+ update_checklist_item,
27
+ update_task_status,
28
+ )
29
+ from .executor import (
30
+ ExecutorConfig,
31
+ ExecutorState,
32
+ TaskAttempt,
33
+ TaskState,
34
+ build_config,
35
+ build_task_prompt,
36
+ execute_task,
37
+ load_config_from_yaml,
38
+ run_with_retries,
39
+ main as executor_main,
40
+ )
41
+
42
+ __version__ = "0.1.0"
43
+ __all__ = [
44
+ # Task management
45
+ "Task",
46
+ "TASKS_FILE",
47
+ "parse_tasks",
48
+ "get_next_tasks",
49
+ "get_task_by_id",
50
+ "resolve_dependencies",
51
+ "update_task_status",
52
+ "update_checklist_item",
53
+ "mark_all_checklist_done",
54
+ # Executor
55
+ "ExecutorConfig",
56
+ "ExecutorState",
57
+ "TaskAttempt",
58
+ "TaskState",
59
+ "build_config",
60
+ "build_task_prompt",
61
+ "execute_task",
62
+ "load_config_from_yaml",
63
+ "run_with_retries",
64
+ "executor_main",
65
+ ]