specag 0.1.0__tar.gz

specag-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+Desktop.ini
+
+# Project runtime
+*.db
+token_usage.db
+agents/state/paused-epics.yaml
+
+# Secrets
+.env
+.env.*
+credentials.json
+*.pem
+*.key
+
+# Rootine Cloud (private — not part of open source)
+cloud/
+
+# User project data (generated by rootine init)
+rootine.config.yaml
+sprints/
+year-*/
+!templates/

specag-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Contributing to SpecAg
+
+Thank you for considering contributing. SpecAg is an early-stage open-source project and every contribution matters.
+
+## Ways to Contribute
+
+### 1. Use it and report back
+
+The most valuable contribution right now is **using SpecAg on a real project** and telling us what broke, what was confusing, or what you wish existed. Open an issue with:
+
+- What you tried to do
+- What happened
+- What you expected
+
+### 2. Improve documentation
+
+Found a confusing paragraph? A missing step in the quick start? A broken link? Fix it and open a PR. Documentation PRs are merged fast.
+
+### 3. Add an example project
+
+Build something small with SpecAg (a todo app, a CLI tool, an API) and submit it to `examples/`. Include:
+
+- `specag.config.yaml` with your tier choice
+- At least 2-3 specs showing the spec-driven flow
+- A README explaining what you built and what tier you used
+
+### 4. Write a custom hook
+
+Implement the `PreCallHook` interface for a use case we haven't covered. Examples:
+
+- A hook that reads blocker status from Jira/Linear instead of a local YAML file
+- A hook that enforces different token caps on weekends vs weekdays
+- A hook that routes different epic categories to different models
+
+### 5. Contribute a tier profile
+
+If you've customized the tier matrix for your use case (e.g., a "regulated" tier between T3 and T4), submit it as a PR to `templates/`.
+
+## Development Setup
+
+```bash
+git clone https://github.com/dedeepyasai/specag.git
+cd specag
+python -m venv .venv
+source .venv/bin/activate    # or .venv\Scripts\activate on Windows
+pip install -e ".[dev]"
+```
+
+### Running tests
+
+```bash
+pytest
+```
+
+### Code style
+
+```bash
+ruff check rootine/
+ruff format rootine/
+```
+
+## Pull Request Guidelines
+
+1. **One PR per change.** Don't bundle unrelated fixes.
+2. **Write a clear description.** What changed, why, and how to test it.
+3. **Follow existing patterns.** Read the code around your change before writing new abstractions.
+4. **No comments unless the WHY is non-obvious.** Code should be self-documenting.
+5. **Test your change.** If you're adding CLI functionality, manually test `specag <command>`.
+
+## Code of Conduct
+
+Be kind. Be constructive. Focus on the work, not the person. This is a blameless project (see the Bible's retro rules — they apply to contributions too).
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

specag-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Datta
+
+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.

specag-0.1.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.1
+Name: specag
+Version: 0.1.0
+Summary: Run an AI engineering team with full cost control and traceability.
+Project-URL: Homepage, https://github.com/dedeepyasai/specag
+Project-URL: Documentation, https://dedeepyasai.github.io/specag-site/documentation.html
+Project-URL: Repository, https://github.com/dedeepyasai/specag
+Project-URL: Issues, https://github.com/dedeepyasai/specag/issues
+Author-email: Dedeepya Sai Gondi <sai.gondi@ieee.org>
+License: MIT
+License-File: LICENSE
+Keywords: agile,ai-agents,cost-control,llm,multi-agent,scrum,spec-driven-development
+Classifier: Development Status :: 3 - Alpha
+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 :: Libraries :: Application Frameworks
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SpecAg
+
+**Run an AI-powered engineering team with full cost control and traceability.**
+
+SpecAg is an open-source, opinionated framework for running real software projects with AI agents doing the development work — using proper Agile ceremonies, spec-driven development, and hard budget guardrails. Built for solo founders and small teams who want AI leverage without AI chaos.
+
+```bash
+pip install specag
+specag init
+```
+
+---
+
+## What SpecAg Does
+
+Most AI coding tools solve the **typing** problem. SpecAg solves the **engineering process** problem.
+
+| Without SpecAg | With SpecAg |
+|---|---|
+| AI burns $200 overnight on a feature you didn't ask for | Hard daily/weekly token caps with automatic pause |
+| No spec, no tests, no review | Every line of code traces back to an approved spec |
+| "What did the AI do while I was at work?" | Full audit trail: spec + prompt + output + cost |
+| Blocked on a human decision? AI keeps burning tokens. | Cascading 1/3/7 day SLA — T+7 = hard pause, zero spend |
+| One-size-fits-all process | Stakes-based tiers: Starter → Personal → Medium → Enterprise |
+
+## The Team
+
+SpecAg gives you a 4-role team. 1 human, 3 AI agents.
+
+| Role | Who | What they do |
+|---|---|---|
+| **Advisor** | You (human) | Vision, architecture, QA, final say. ~10 hrs/week. |
+| **Lead Dev** | AI agent | Architecture, complex features, PR reviews |
+| **Associate** | AI agent | Smaller features, tests, infra scripts |
+| **PO Agent** | AI agent | Backlog, ceremonies, daily reports, process glue |
+
+All coordination happens over Slack. No meetings. No Jira.
+
+## Quick Start
+
+```bash
+# Install
+pip install specag
+
+# Initialize a new project (interactive tier picker)
+specag init
+
+# Prepare next sprint (Saturday)
+specag sprint prepare
+
+# Kick off sprint (Sunday)
+specag sprint kickoff
+
+# Check cost and token usage
+specag stats
+```
+
+See [Quick Start Guide](docs/quick-start.md) for the full 10-minute walkthrough.
+
+## Stakes-Based Tiers
+
+SpecAg tiers projects by **stakes, not user count**. A HIPAA app with 20 users needs more rigor than a meme app with 10M users.
+
+| Tier | When to use | Ceremonies | Spec required | Cost enforcement |
+|---|---|---|---|---|
+| **T1 Starter** | Learning, experiments, tutorials | Optional | Optional | Always on |
+| **T2 Personal** | Real side project, solo owner | Recommended | Recommended | Always on |
+| **T3 Medium** | Paying users, real revenue | Required | Required | Always on |
+
+> **Cost enforcement is strict at every tier.** That's the point. Even a hello-world project gets token caps, because the point is to prevent runaway spend.
+
+Set your tier in `specag.config.yaml`:
+
+```yaml
+project:
+  name: "my-project"
+  tier: personal    # starter | personal | medium
+```
+
+See [Tier Matrix](docs/tier-matrix.md) for the full strictness breakdown.
+
+## Cost Enforcement (The Moat)
+
+Every AI coding tool watches your spend. **SpecAg stops it.**
+
+### Pre-Call Hook Chain
+
+Before any LLM API call, a chain of hooks runs. First non-ALLOW decision wins:
+
+| Hook | What it does |
+|---|---|
+| `DailyCapHook` | Reject if daily token cap reached |
+| `WeeklyCapHook` | Reject if weekly cap reached |
+| `WorkWindowHook` | Reject if outside work hours |
+| `PausedRegistryHook` | Reject if epic is hard-paused (blocker T+7) |
+| `PCModeHook` | Downgrade to cheaper model during discovery phases |
+| `BudgetGuardHook` | Reject if estimated cost exceeds remaining budget |
+
+Hooks are pluggable. Swap, add, or remove by editing `hooks.yaml` — no code changes.
+
+### Cascading Blocker SLA
+
+When work is blocked on a human decision:
+
+| Day | What happens |
+|---|---|
+| **T+1** | PO Agent nudges in Slack |
+| **T+3** | Priority bumps. Downstream impact broadcast. |
+| **T+7** | **HARD PAUSE.** Token tracker rejects ALL LLM calls on blocked paths. Zero spend until human responds. |
+
+Most tools observe. SpecAg enforces.
+
+## Spec-Driven Development
+
+No code without a spec. No commit without a spec reference. No PR without a spec update.
+
+```
+Spec (business + technical + acceptance criteria)
+  → AI implements against the spec
+  → Commit references the spec (git hook enforces)
+  → PR updates the spec changelog (CI enforces)
+  → Demo proves the spec works
+  → Human accepts
+```
+
+AI agents have no memory between conversations. **The spec IS their memory.**
+
+## Honest Comparison
+
+SpecAg is inspired by and builds on ideas from [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD), [GitHub Spec Kit](https://github.com/github/spec-kit), and [MetaGPT](https://github.com/FoundationAgents/MetaGPT). Here's what's different:
+
+| Feature | BMAD | Spec Kit | MetaGPT | **SpecAg** |
+|---|---|---|---|---|
+| Agent roles (PM, Dev, etc.) | Yes | No | Yes | Yes |
+| Spec-driven development | Yes | Yes | Partial | Yes |
+| Token cost enforcement (hard stop) | No | No | No | **Yes** |
+| Cascading blocker SLA (T+7 hard pause) | No | No | No | **Yes** |
+| Stakes-based tier system | No | No | No | **Yes** |
+| Sustainable pace ceiling | No | No | No | **Yes** |
+| Pluggable hook architecture | No | Partial | No | **Yes** |
+| Solo-founder-with-day-job persona | No | No | No | **Yes** |
+
+We don't pretend to be unique in every dimension. We're unique where it matters: **cost control + human-compatible pacing.**
+
+## Documentation
+
+| Doc | What it covers |
+|---|---|
+| [Quick Start](docs/quick-start.md) | Zero to first spec in 10 minutes |
+| [Study Guide](docs/study-guide.md) | Learning path for understanding the full framework |
+| [Project Bible](docs/bible.md) | The complete methodology reference (~2000 lines) |
+| [Tier Matrix](docs/tier-matrix.md) | What's strict/lenient at each tier |
+| [Architecture](docs/architecture.md) | How the pieces fit together |
+| [Roadmap](docs/roadmap.md) | What's built, what's next |
+
+## Who This Is For
+
+- **Solo founders with a day job** who want AI leverage without full-time babysitting
+- **Small teams (2-5)** adopting AI agents for real production work
+- **Anyone burned by "vibe coding"** who wants the discipline layer back
+
+## Who This Is NOT For
+
+- Teams that want fully autonomous AI (try [Devin](https://devin.ai))
+- Teams that just need code completion (try [Cursor](https://cursor.sh) or [Copilot](https://github.com/features/copilot))
+- Enterprise teams that need Jira/Linear integration today (that's on the roadmap, not shipped)
+
+## Estimated Cost
+
+Running a full SpecAg team (1 human + 3 AI agents) for a year:
+
+| Item | Annual cost |
+|---|---|
+| VPS (4 vCPU / 16GB) | ~$144 |
+| AI APIs (primary + fallback) | ~$280 |
+| **Total** | **~$424/year ($35/month)** |
+
+The framework is designed to stay under $500/year total. Cost enforcement makes this a ceiling, not a guess.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). We welcome:
+- Bug reports and feature requests
+- Documentation improvements
+- New hook implementations
+- Tier profile contributions
+- Example projects
+
+## License
+
+MIT. Use it, fork it, sell products built with it. See [LICENSE](LICENSE).
+
+---
+
+*Built by [Dedeepya Sai Gondi](https://github.com/dedeepyasai) in Dallas, TX. Dogfooded on real projects.*

specag-0.1.0/README.md

@@ -0,0 +1,195 @@
+# SpecAg
+
+**Run an AI-powered engineering team with full cost control and traceability.**
+
+SpecAg is an open-source, opinionated framework for running real software projects with AI agents doing the development work — using proper Agile ceremonies, spec-driven development, and hard budget guardrails. Built for solo founders and small teams who want AI leverage without AI chaos.
+
+```bash
+pip install specag
+specag init
+```
+
+---
+
+## What SpecAg Does
+
+Most AI coding tools solve the **typing** problem. SpecAg solves the **engineering process** problem.
+
+| Without SpecAg | With SpecAg |
+|---|---|
+| AI burns $200 overnight on a feature you didn't ask for | Hard daily/weekly token caps with automatic pause |
+| No spec, no tests, no review | Every line of code traces back to an approved spec |
+| "What did the AI do while I was at work?" | Full audit trail: spec + prompt + output + cost |
+| Blocked on a human decision? AI keeps burning tokens. | Cascading 1/3/7 day SLA — T+7 = hard pause, zero spend |
+| One-size-fits-all process | Stakes-based tiers: Starter → Personal → Medium → Enterprise |
+
+## The Team
+
+SpecAg gives you a 4-role team. 1 human, 3 AI agents.
+
+| Role | Who | What they do |
+|---|---|---|
+| **Advisor** | You (human) | Vision, architecture, QA, final say. ~10 hrs/week. |
+| **Lead Dev** | AI agent | Architecture, complex features, PR reviews |
+| **Associate** | AI agent | Smaller features, tests, infra scripts |
+| **PO Agent** | AI agent | Backlog, ceremonies, daily reports, process glue |
+
+All coordination happens over Slack. No meetings. No Jira.
+
+## Quick Start
+
+```bash
+# Install
+pip install specag
+
+# Initialize a new project (interactive tier picker)
+specag init
+
+# Prepare next sprint (Saturday)
+specag sprint prepare
+
+# Kick off sprint (Sunday)
+specag sprint kickoff
+
+# Check cost and token usage
+specag stats
+```
+
+See [Quick Start Guide](docs/quick-start.md) for the full 10-minute walkthrough.
+
+## Stakes-Based Tiers
+
+SpecAg tiers projects by **stakes, not user count**. A HIPAA app with 20 users needs more rigor than a meme app with 10M users.
+
+| Tier | When to use | Ceremonies | Spec required | Cost enforcement |
+|---|---|---|---|---|
+| **T1 Starter** | Learning, experiments, tutorials | Optional | Optional | Always on |
+| **T2 Personal** | Real side project, solo owner | Recommended | Recommended | Always on |
+| **T3 Medium** | Paying users, real revenue | Required | Required | Always on |
+
+> **Cost enforcement is strict at every tier.** That's the point. Even a hello-world project gets token caps, because the point is to prevent runaway spend.
+
+Set your tier in `specag.config.yaml`:
+
+```yaml
+project:
+  name: "my-project"
+  tier: personal    # starter | personal | medium
+```
+
+See [Tier Matrix](docs/tier-matrix.md) for the full strictness breakdown.
+
+## Cost Enforcement (The Moat)
+
+Every AI coding tool watches your spend. **SpecAg stops it.**
+
+### Pre-Call Hook Chain
+
+Before any LLM API call, a chain of hooks runs. First non-ALLOW decision wins:
+
+| Hook | What it does |
+|---|---|
+| `DailyCapHook` | Reject if daily token cap reached |
+| `WeeklyCapHook` | Reject if weekly cap reached |
+| `WorkWindowHook` | Reject if outside work hours |
+| `PausedRegistryHook` | Reject if epic is hard-paused (blocker T+7) |
+| `PCModeHook` | Downgrade to cheaper model during discovery phases |
+| `BudgetGuardHook` | Reject if estimated cost exceeds remaining budget |
+
+Hooks are pluggable. Swap, add, or remove by editing `hooks.yaml` — no code changes.
+
+### Cascading Blocker SLA
+
+When work is blocked on a human decision:
+
+| Day | What happens |
+|---|---|
+| **T+1** | PO Agent nudges in Slack |
+| **T+3** | Priority bumps. Downstream impact broadcast. |
+| **T+7** | **HARD PAUSE.** Token tracker rejects ALL LLM calls on blocked paths. Zero spend until human responds. |
+
+Most tools observe. SpecAg enforces.
+
+## Spec-Driven Development
+
+No code without a spec. No commit without a spec reference. No PR without a spec update.
+
+```
+Spec (business + technical + acceptance criteria)
+  → AI implements against the spec
+  → Commit references the spec (git hook enforces)
+  → PR updates the spec changelog (CI enforces)
+  → Demo proves the spec works
+  → Human accepts
+```
+
+AI agents have no memory between conversations. **The spec IS their memory.**
+
+## Honest Comparison
+
+SpecAg is inspired by and builds on ideas from [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD), [GitHub Spec Kit](https://github.com/github/spec-kit), and [MetaGPT](https://github.com/FoundationAgents/MetaGPT). Here's what's different:
+
+| Feature | BMAD | Spec Kit | MetaGPT | **SpecAg** |
+|---|---|---|---|---|
+| Agent roles (PM, Dev, etc.) | Yes | No | Yes | Yes |
+| Spec-driven development | Yes | Yes | Partial | Yes |
+| Token cost enforcement (hard stop) | No | No | No | **Yes** |
+| Cascading blocker SLA (T+7 hard pause) | No | No | No | **Yes** |
+| Stakes-based tier system | No | No | No | **Yes** |
+| Sustainable pace ceiling | No | No | No | **Yes** |
+| Pluggable hook architecture | No | Partial | No | **Yes** |
+| Solo-founder-with-day-job persona | No | No | No | **Yes** |
+
+We don't pretend to be unique in every dimension. We're unique where it matters: **cost control + human-compatible pacing.**
+
+## Documentation
+
+| Doc | What it covers |
+|---|---|
+| [Quick Start](docs/quick-start.md) | Zero to first spec in 10 minutes |
+| [Study Guide](docs/study-guide.md) | Learning path for understanding the full framework |
+| [Project Bible](docs/bible.md) | The complete methodology reference (~2000 lines) |
+| [Tier Matrix](docs/tier-matrix.md) | What's strict/lenient at each tier |
+| [Architecture](docs/architecture.md) | How the pieces fit together |
+| [Roadmap](docs/roadmap.md) | What's built, what's next |
+
+## Who This Is For
+
+- **Solo founders with a day job** who want AI leverage without full-time babysitting
+- **Small teams (2-5)** adopting AI agents for real production work
+- **Anyone burned by "vibe coding"** who wants the discipline layer back
+
+## Who This Is NOT For
+
+- Teams that want fully autonomous AI (try [Devin](https://devin.ai))
+- Teams that just need code completion (try [Cursor](https://cursor.sh) or [Copilot](https://github.com/features/copilot))
+- Enterprise teams that need Jira/Linear integration today (that's on the roadmap, not shipped)
+
+## Estimated Cost
+
+Running a full SpecAg team (1 human + 3 AI agents) for a year:
+
+| Item | Annual cost |
+|---|---|
+| VPS (4 vCPU / 16GB) | ~$144 |
+| AI APIs (primary + fallback) | ~$280 |
+| **Total** | **~$424/year ($35/month)** |
+
+The framework is designed to stay under $500/year total. Cost enforcement makes this a ceiling, not a guess.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). We welcome:
+- Bug reports and feature requests
+- Documentation improvements
+- New hook implementations
+- Tier profile contributions
+- Example projects
+
+## License
+
+MIT. Use it, fork it, sell products built with it. See [LICENSE](LICENSE).
+
+---
+
+*Built by [Dedeepya Sai Gondi](https://github.com/dedeepyasai) in Dallas, TX. Dogfooded on real projects.*