agentscaffold 0.1.0__tar.gz

agentscaffold-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+*.so
+
+.venv/
+venv/
+env/
+
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+htmlcov/
+.coverage
+coverage.xml
+
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db

agentscaffold-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dave Robb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentscaffold-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: agentscaffold
+Version: 0.1.0
+Summary: Structured AI-assisted development framework with plan lifecycle, review gates, and continuous improvement.
+Project-URL: Homepage, https://github.com/drobbster/agentscaffold
+Project-URL: Documentation, https://github.com/drobbster/agentscaffold#readme
+Project-URL: Repository, https://github.com/drobbster/agentscaffold
+Project-URL: Issues, https://github.com/drobbster/agentscaffold/issues
+Author: Dave Robb
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,claude,cursor,development,llm,scaffolding,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AgentScaffold
+
+Structured AI-assisted development framework with plan lifecycle, review gates, and continuous improvement.
+
+## What Is This?
+
+AgentScaffold gives your AI coding agent (Cursor, Claude Code, Codex, aider, etc.) a structured development workflow. It generates an `AGENTS.md` file that teaches your agent to:
+
+- Follow a **plan lifecycle** (Draft -> Review -> Ready -> In Progress -> Complete) with configurable gates
+- Run **devil's advocate** and **expansion reviews** before execution
+- Maintain **interface contracts** between modules
+- Complete **retrospectives** after every plan, feeding learnings back into the process
+- Track state across sessions via **workflow state**, **learnings tracker**, and **plan completion log**
+
+## Quick Start
+
+```bash
+pip install agentscaffold
+cd my-project
+scaffold init
+```
+
+The `init` command scaffolds your project with:
+
+- `docs/ai/` -- templates, prompts, standards, state files
+- `AGENTS.md` -- rules your AI agent follows automatically
+- `.cursor/rules.md` -- Cursor-specific rules
+- `scaffold.yaml` -- your project's framework configuration
+- `justfile` + `Makefile` -- task runner shortcuts
+- `.github/workflows/` -- CI with security scanning
+
+## Execution Profiles
+
+**Interactive** (default): Human + AI agent in an IDE conversation. The agent follows AGENTS.md, asks questions when uncertain.
+
+**Semi-Autonomous** (opt-in): Agent invoked from CLI/CI without a human present. Adds session tracking, safety boundaries, notification hooks, structured PR output, and cautious execution rules.
+
+Both profiles coexist in the same AGENTS.md. The agent self-selects based on invocation context.
+
+## Rigor Levels
+
+- **Minimal**: Lightweight gates for prototypes and small projects
+- **Standard**: Full plan lifecycle with reviews, contracts, and retrospectives
+- **Strict**: All gates enforced, all plans require approval
+
+## Domain Packs
+
+Domain packs add specialized review prompts, standards, and approval gates:
+
+| Pack | Focus |
+|------|-------|
+| trading | Quantitative finance, RL, traceability |
+| webapp | UX/UI, accessibility, performance budgets |
+| mlops | Model lifecycle, experiment tracking, drift detection |
+| data-engineering | Pipeline quality, schema evolution, SLAs |
+| api-services | API design, backward compatibility, contract testing |
+| infrastructure | IaC, deployment safety, cost analysis |
+| mobile | Platform guidelines, offline-first, app store compliance |
+| game-dev | Game loops, ECS, frame budgets |
+| embedded | Memory constraints, real-time deadlines, OTA safety |
+| research | Reproducibility, statistical rigor, experiment protocol |
+
+```bash
+scaffold domain add trading
+scaffold domain add webapp
+```
+
+## CLI Commands
+
+```bash
+scaffold init                          # Set up framework
+scaffold plan create my-feature        # Create a plan
+scaffold plan lint --plan 001          # Validate a plan
+scaffold plan status                   # Dashboard of all plans
+scaffold validate                      # Run all checks
+scaffold retro check                   # Find missing retrospectives
+scaffold agents generate               # Regenerate AGENTS.md
+scaffold cursor setup                  # Regenerate .cursor/rules.md
+scaffold import chat.json --format chatgpt  # Import conversation
+scaffold ci setup                      # Generate CI workflows
+scaffold taskrunner setup              # Generate justfile + Makefile
+scaffold metrics                       # Plan analytics
+```
+
+## Documentation
+
+Full documentation is in [docs/](docs/):
+
+- [User Guide](docs/user-guide.md) -- interaction patterns and session workflow
+- [Getting Started](docs/getting-started.md)
+- [Configuration Reference](docs/configuration.md)
+- [Domain Packs](docs/domain-packs.md)
+- [Semi-Autonomous Guide](docs/semi-autonomous-guide.md)
+- [CI Integration](docs/ci-integration.md)
+
+## License
+
+MIT

agentscaffold-0.1.0/README.md

@@ -0,0 +1,98 @@
+# AgentScaffold
+
+Structured AI-assisted development framework with plan lifecycle, review gates, and continuous improvement.
+
+## What Is This?
+
+AgentScaffold gives your AI coding agent (Cursor, Claude Code, Codex, aider, etc.) a structured development workflow. It generates an `AGENTS.md` file that teaches your agent to:
+
+- Follow a **plan lifecycle** (Draft -> Review -> Ready -> In Progress -> Complete) with configurable gates
+- Run **devil's advocate** and **expansion reviews** before execution
+- Maintain **interface contracts** between modules
+- Complete **retrospectives** after every plan, feeding learnings back into the process
+- Track state across sessions via **workflow state**, **learnings tracker**, and **plan completion log**
+
+## Quick Start
+
+```bash
+pip install agentscaffold
+cd my-project
+scaffold init
+```
+
+The `init` command scaffolds your project with:
+
+- `docs/ai/` -- templates, prompts, standards, state files
+- `AGENTS.md` -- rules your AI agent follows automatically
+- `.cursor/rules.md` -- Cursor-specific rules
+- `scaffold.yaml` -- your project's framework configuration
+- `justfile` + `Makefile` -- task runner shortcuts
+- `.github/workflows/` -- CI with security scanning
+
+## Execution Profiles
+
+**Interactive** (default): Human + AI agent in an IDE conversation. The agent follows AGENTS.md, asks questions when uncertain.
+
+**Semi-Autonomous** (opt-in): Agent invoked from CLI/CI without a human present. Adds session tracking, safety boundaries, notification hooks, structured PR output, and cautious execution rules.
+
+Both profiles coexist in the same AGENTS.md. The agent self-selects based on invocation context.
+
+## Rigor Levels
+
+- **Minimal**: Lightweight gates for prototypes and small projects
+- **Standard**: Full plan lifecycle with reviews, contracts, and retrospectives
+- **Strict**: All gates enforced, all plans require approval
+
+## Domain Packs
+
+Domain packs add specialized review prompts, standards, and approval gates:
+
+| Pack | Focus |
+|------|-------|
+| trading | Quantitative finance, RL, traceability |
+| webapp | UX/UI, accessibility, performance budgets |
+| mlops | Model lifecycle, experiment tracking, drift detection |
+| data-engineering | Pipeline quality, schema evolution, SLAs |
+| api-services | API design, backward compatibility, contract testing |
+| infrastructure | IaC, deployment safety, cost analysis |
+| mobile | Platform guidelines, offline-first, app store compliance |
+| game-dev | Game loops, ECS, frame budgets |
+| embedded | Memory constraints, real-time deadlines, OTA safety |
+| research | Reproducibility, statistical rigor, experiment protocol |
+
+```bash
+scaffold domain add trading
+scaffold domain add webapp
+```
+
+## CLI Commands
+
+```bash
+scaffold init                          # Set up framework
+scaffold plan create my-feature        # Create a plan
+scaffold plan lint --plan 001          # Validate a plan
+scaffold plan status                   # Dashboard of all plans
+scaffold validate                      # Run all checks
+scaffold retro check                   # Find missing retrospectives
+scaffold agents generate               # Regenerate AGENTS.md
+scaffold cursor setup                  # Regenerate .cursor/rules.md
+scaffold import chat.json --format chatgpt  # Import conversation
+scaffold ci setup                      # Generate CI workflows
+scaffold taskrunner setup              # Generate justfile + Makefile
+scaffold metrics                       # Plan analytics
+```
+
+## Documentation
+
+Full documentation is in [docs/](docs/):
+
+- [User Guide](docs/user-guide.md) -- interaction patterns and session workflow
+- [Getting Started](docs/getting-started.md)
+- [Configuration Reference](docs/configuration.md)
+- [Domain Packs](docs/domain-packs.md)
+- [Semi-Autonomous Guide](docs/semi-autonomous-guide.md)
+- [CI Integration](docs/ci-integration.md)
+
+## License
+
+MIT

agentscaffold-0.1.0/docs/README.md

@@ -0,0 +1,11 @@
+# AgentScaffold Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Getting Started](getting-started.md) | Installation, init, first plan, review, execution, retrospective, validation |
+| [Configuration](configuration.md) | Full scaffold.yaml reference, gates, rigor presets |
+| [Domain Packs](domain-packs.md) | Available packs, installation, using multiple packs |
+| [Creating Domain Packs](creating-domain-packs.md) | Structure, manifest, prompts, standards |
+| [Semi-Autonomous Guide](semi-autonomous-guide.md) | CLI/CI agent mode, session tracking, safety, notifications |
+| [Importing Conversations](importing-conversations.md) | ChatGPT, markdown, Claude exports |
+| [CI Integration](ci-integration.md) | scaffold ci setup, workflows, task runner |

agentscaffold-0.1.0/docs/ci-integration.md

@@ -0,0 +1,130 @@
+# CI Integration
+
+AgentScaffold generates GitHub Actions workflows and task runner files to integrate the framework into your CI pipeline.
+
+## scaffold ci setup
+
+From your project root:
+
+```bash
+scaffold ci setup
+```
+
+This generates files based on your `scaffold.yaml` configuration. Run it after changing CI-related settings (e.g. enabling semi-autonomous, toggling plan lint).
+
+## Generated Workflows
+
+### ci.yml (main CI)
+
+Runs on push and pull request to `main`:
+
+- Checkout and Python setup
+- Install dependencies (`pip install -e ".[dev]"`)
+- Lint (`ruff check .`)
+- Test (`pytest -q`)
+- Study lint (`scaffold study lint`) if `ci.study_lint: true`
+- Plan lint (`scaffold plan lint`) if `ci.plan_lint: true` (strict rigor)
+
+### security.yml (security scanning)
+
+Runs on push and pull request to `main` when `ci.security_scanning: true`:
+
+- Bandit SAST (`bandit -r src/ -ll`)
+- TruffleHog for secret detection (`trufflesecurity/trufflehog` with `--only-verified`)
+
+### semi-autonomous-pr.yml (agent PR validation)
+
+Generated when `semi_autonomous.enabled: true` and `ci.semi_autonomous_pr_checks: true`. Runs on pull requests that:
+
+- Have the `agent-created` label, or
+- Have a branch name starting with `agent/`
+
+Steps:
+
+- Checkout and Python setup
+- Install dependencies
+- `scaffold validate --check-safety-boundaries`
+- `scaffold validate --check-session-summary`
+- Full test suite
+- Lint
+
+When semi-autonomous is enabled, `scaffold ci setup` also generates:
+
+- `.github/pull_request_template.md` (PR template for agent PRs)
+- `scripts/notify.py` (notification helper script)
+
+## Customizing Generated Workflows
+
+Generated files are overwritten each time you run `scaffold ci setup`. To customize:
+
+1. **Edit after generation**: Modify the generated YAML files. Re-running `scaffold ci setup` will overwrite them, so document your changes or maintain a patch.
+
+2. **Add separate workflows**: Create additional workflow files (e.g. `.github/workflows/custom.yml`) that run alongside the generated ones. The generator does not touch files it did not create.
+
+3. **Adjust scaffold.yaml**: Toggle `security_scanning`, `study_lint`, `plan_lint`, and `semi_autonomous_pr_checks` to control what gets generated.
+
+## Running scaffold validate in CI
+
+Add a validation step to any workflow:
+
+```yaml
+- name: Validate
+  run: scaffold validate
+```
+
+For agent-created PRs, use the optional flags:
+
+```yaml
+- name: Validate safety boundaries
+  run: scaffold validate --check-safety-boundaries
+- name: Validate session summary
+  run: scaffold validate --check-session-summary
+```
+
+Ensure `agentscaffold` is installed (e.g. `pip install agentscaffold` or `pip install -e ".[dev]"` if it is a project dependency).
+
+## Task Runner Integration
+
+Generate task runner files:
+
+```bash
+scaffold taskrunner setup
+```
+
+Options:
+
+```bash
+scaffold taskrunner setup --format both    # justfile + Makefile (default)
+scaffold taskrunner setup --format justfile
+scaffold taskrunner setup --format makefile
+```
+
+### justfile
+
+Provides targets such as:
+
+- `lint-plans`, `plan-status`, `check-retros`, `validate`, `study-lint`, `metrics`
+- `agents-generate`, `cursor-setup`
+- `lint`, `format`, `test`, `test-cov`
+- `ci-setup`
+- `validate-safety`, `validate-session` (when semi-autonomous enabled)
+
+### Makefile
+
+Similar targets for environments where `make` is preferred over `just`.
+
+### Usage
+
+```bash
+just validate
+just lint-plans
+just test
+```
+
+Or with Make:
+
+```bash
+make validate
+make lint-plans
+make test
+```

agentscaffold-0.1.0/docs/configuration.md

@@ -0,0 +1,248 @@
+# Configuration Reference
+
+This document describes every section and field in `scaffold.yaml`. After editing, run `scaffold agents generate` to regenerate AGENTS.md.
+
+## Top-Level Sections
+
+### framework
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| version | string | "1.0" | Framework version (informational) |
+| project_name | string | "My Project" | Project name used in templates |
+| architecture_layers | int | 6 | Number of layers in system architecture |
+
+### profile
+
+| Value | Description |
+|-------|-------------|
+| interactive | Human + AI in IDE. Agent asks questions when uncertain. |
+| semi_autonomous | Agent invoked from CLI/CI without human. Adds session tracking, safety boundaries, notifications. |
+
+Default: `interactive`
+
+### rigor
+
+| Value | Description |
+|-------|-------------|
+| minimal | Lightweight gates for prototypes and small projects |
+| standard | Full plan lifecycle with reviews, contracts, retrospectives |
+| strict | All gates enforced, domain implementation review, approval required |
+
+Default: `standard`
+
+### domains
+
+List of installed domain pack names (e.g. `trading`, `webapp`, `mlops`). Domain packs add review prompts, standards, and approval gates. See [Domain Packs](domain-packs.md).
+
+Default: `[]`
+
+---
+
+## Gates
+
+Gates control transitions between plan lifecycle states: Draft -> Review -> Ready -> In Progress -> Complete.
+
+### gates.draft_to_review
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| plan_lint | bool | true | Require plan lint to pass |
+| architecture_layer_check | bool | true | Verify plan maps to a layer in system_architecture.md |
+
+### gates.review_to_ready
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| devils_advocate | bool | true | Require devil's advocate review |
+| expansion_review | bool | true | Require expansion/gap analysis review |
+| domain_reviews | list[str] | [] | Domain-specific review names (from domain packs) |
+| spike_for_high_uncertainty | bool | true | Require spike when plan has high uncertainty |
+| interface_contracts | bool | true | Require interface contracts for exports |
+| security_review | bool | true | Require security review when applicable |
+
+### gates.ready_to_in_progress
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| review_checklist | bool | true | Require plan review checklist completed |
+| approval_gates | bool | true | Require human approval for approval-required changes |
+| interactive_gate | bool | true | Require human confirmation when "review it with me" requested |
+
+### gates.in_progress_to_complete
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| all_steps_checked | bool | true | All execution steps must be checked off |
+| validation_commands | bool | true | Validation commands must pass |
+| tests_pass | bool | true | Tests must pass |
+| retrospective | bool | true | Retrospective must be completed |
+| domain_implementation_review | bool | false | Domain-specific post-implementation review (e.g. quant_architect_implementation) |
+
+---
+
+## Rigor Presets
+
+Rigor presets override gate defaults. The preset is applied when loading config.
+
+### minimal
+
+- `architecture_layer_check`: false
+- `devils_advocate`, `expansion_review`, `spike_for_high_uncertainty`, `interface_contracts`, `security_review`: false
+- `review_checklist`, `approval_gates`, `interactive_gate`: false
+- `retrospective`: false
+
+### standard
+
+No overrides. Uses default gate values.
+
+### strict
+
+- `security_review`: true
+- `approval_gates`: true
+- `domain_implementation_review`: true
+- `ci.plan_lint`: true
+
+---
+
+## approval_required
+
+Determines which change types require human approval before execution.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| breaking_changes | bool | true | Breaking API/schema changes |
+| security_sensitive | bool | true | Auth, crypto, secrets |
+| data_migrations | bool | true | Database migrations |
+| infrastructure | bool | true | Terraform, Docker, infra |
+| external_apis | bool | true | External API integrations |
+
+Domain packs can add approval gates (e.g. `financial_calculations`, `model_deployment`).
+
+---
+
+## standards
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| core | list[str] | ["errors", "logging", "config", "testing"] | Core standards referenced in plans |
+| domain | list[str] | [] | Domain-specific standards (from domain packs) |
+
+---
+
+## prohibitions
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| emojis | bool | false | Forbid emojis in code, docs, logs |
+| patterns | list[str] | [] | Regex patterns to forbid (e.g. `TODO`, `FIXME`) |
+
+---
+
+## agents
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| agents_md | bool | true | Generate AGENTS.md |
+| cursor_rules | bool | true | Generate .cursor/rules.md |
+
+---
+
+## semi_autonomous
+
+Only applies when `profile: semi_autonomous` or `semi_autonomous.enabled: true`.
+
+### semi_autonomous.enabled
+
+| Type | Default | Description |
+|------|---------|-------------|
+| bool | false | Enable semi-autonomous enhancements |
+
+### semi_autonomous.session_tracking
+
+| Type | Default | Description |
+|------|---------|-------------|
+| bool | true | Track agent sessions in docs/ai/state/sessions/ |
+
+### semi_autonomous.context_handoff
+
+| Type | Default | Description |
+|------|---------|-------------|
+| bool | true | Support context handoff between sessions |
+
+### semi_autonomous.safety
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| read_only_paths | list[str] | ["docs/ai/system_architecture.md", "scaffold.yaml", ".github/"] | Paths the agent must not modify |
+| require_approval_paths | list[str] | ["infra/", "docs/security/"] | Paths requiring human approval before modification |
+
+### semi_autonomous.notifications
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| enabled | bool | true | Enable notification hooks |
+| channel | str | "github_issue" | `stdout`, `github_issue`, or `slack` |
+| slack_webhook_env | str | "SLACK_WEBHOOK_URL" | Env var for Slack webhook URL |
+| notify_on | list[str] | ["plan_complete", "escalation", "validation_failure", "approval_required"] | Events that trigger notifications |
+
+### semi_autonomous.cautious_execution
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| max_fix_attempts | int | 2 | Max auto-fix attempts before escalation |
+| max_new_files_before_escalation | int | 5 | Max new files before escalating for review |
+
+---
+
+## import
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| conversation_dir | str | "data/conversations" | Directory for imported conversation files |
+
+---
+
+## task_runner
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| justfile | bool | true | Generate justfile |
+| makefile | bool | true | Generate Makefile |
+
+---
+
+## ci
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| provider | str | "github" | CI provider (only `github` supported) |
+| security_scanning | bool | true | Generate security workflow (Bandit, TruffleHog) |
+| study_lint | bool | true | Run `scaffold study lint` in CI |
+| plan_lint | bool | false | Run `scaffold plan lint` in CI (true for strict rigor) |
+| semi_autonomous_pr_checks | bool | false | Generate semi-autonomous PR validation workflow |
+
+---
+
+## How Gates Interact with Lifecycle
+
+```
+Draft --[draft_to_review]--> Review --[review_to_ready]--> Ready
+  |                              |                            |
+  | plan_lint                    | devils_advocate            | review_checklist
+  | architecture_layer_check     | expansion_review           | approval_gates
+                                 | domain_reviews             | interactive_gate
+                                 | spike_for_high_uncertainty |
+                                 | interface_contracts        |
+                                 | security_review            |
+
+Ready --[ready_to_in_progress]--> In Progress --[in_progress_to_complete]--> Complete
+                                        |                                    |
+                                        |                                    | all_steps_checked
+                                        |                                    | validation_commands
+                                        |                                    | tests_pass
+                                        |                                    | retrospective
+                                        |                                    | domain_implementation_review
+```
+
+Disabling a gate skips that requirement. For example, `devils_advocate: false` allows a plan to move from Review to Ready without running the devil's advocate prompt.