<!-- README header: paste ABOVE the existing content -->
<p align="center">
<img src=".github/banner/CoaCoALogo.png" alt="CoaCoA logo" width="150">
</p>
<p align="center">
<a href="https://pypi.org/project/coacoa/">
<img src="https://img.shields.io/pypi/v/coacoa.svg?color=blue&logo=pypi&label=PyPI%20Version" alt="PyPI">
</a>
<a href="https://github.com/im-shashanks/coacoa/blob/main/LICENSE">
<img src="https://img.shields.io/badge/license-Apache--2.0-green.svg" alt="License">
</a>
<a href="https://github.com/im-shashanks/CoaCoA/actions/workflows/ci.yml">
<img
src="https://img.shields.io/github/actions/workflow/status/im-shashanks/CoaCoA/ci.yml?branch=main&label=CI%20build"
alt="CI build status"
>
</a>
<a href="https://codecov.io/gh/im-shashanks/CoaCoA">
<img src=".github/assets/coverage.svg" alt="coverage">
</a>
</p>
# CoaCoA (*v0.1.0b1*) — Context aware Coding Assitant
**Context-Optimised Agentic Coding Assistant**
- *“Drop it in, branch out, ship confidently.”*
---
## 📌 TL;DR
1. `pip install --pre coacoa` *(you can also directly copy the `coacoa/` folder, after git clone `<repo>` if you prefer.)*
*(--pre flag is required because this is a beta version)*
> ⚠️ **Note:** CoaCoA is currently in public beta (`0.1.0b1`).
> To install, use the `--pre` flag with pip as shown above.
> The stable release (`0.1.0`) will follow soon.
2. `coacoa init` *(or manual copy) — scaffolds `coacoa/`, `CLAUDE.md`, `.clinerules`*
3. `git add . && git commit -m "init coa"`
4. In your IDE (Claude Code / Cline):
```text
/analyze-codebase # brown-field │ or │ /analyst init # green-field
/pm new-prd
/ux-designer make-ui
/po refine-epics
/architect finalize-arch
/scrum-master create
/orchestrator run # Dev → QA loop
```
5. Review staged branch feature/s_001_01, commit & push.
6. Rinse, repeat → production-ready PRs with ≥ 90 % test coverage and zero broken builds.
## 🏃♂️ CLI quick-start
> **Virtual-env:** Create virtualenv `.venv` at the project root `python3 -m venv .venv`
> All build, test, and lint commands run inside that venv, keeping global Python untouched.
```bash
# run with explicit sub-command
coacoa init --claude-code # scaffold + create CLAUDE.md
# or simply run without a sub-command (same as `init`)
coacoa --claude-code
```
### Getting help
| Command | Shows… |
| - | - |
| coacoa --help | Global options and the list of sub-commands (init, version, …) |
| coacoa init --help | The per-command flags: --claude-code, --cline |
-Tip – Running coacoa with no arguments is equivalent to coacoa init, so you can type the shorter form once you’re familiar with the flags.
### 🔧 Configuration
• Default settings live in **.coacoa/coacoa.yaml** (ignored by Git).
• Create **coacoa.yaml** at project root to override any key; values deep-merge on top of the defaults.
## ✨ Why CoaCoA?
| Area | CoaCoA v0.1 |
| - | - |
| Config schema | 28-key namespaced YAML |
| Code-intel | map + deps + complexity + hotspots + coverage + cycles + build_info |
| Quality gates | 🎯 5 checklists (Anti-Hallucination, Link, QA, Arch, Build) |
| Workflow | 12 agents (UX, PO, Architect, Code-Explorer, Orchestrator) |
| Branching | auto feature/<story> branch (staged, not committed) |
| SOLID policy | Pragmatic SRP/OCP mandatory, rest advisory via ADR |
## 🗂 Folder & file map
coacoa/
├─ coacoa.yaml ← config (paths, limits, workflows…)
├─ agents/ ← markdown specs (analyst, pm, … orchestrator)
├─ tasks/ ← step-by-step recipes (analyze_codebase.md …)
├─ templates/ ← PRD, UI/UX, architecture, story, ADR…
├─ quality/ ← checklists (anti_hallucination, build_integrity…)
├─ data/ ← tech_preferences.md, solid_policy.md, style_guides/
├─ workflows/ ← default_greenfield.yml, default_brownfield.yml
└─ context/ ← generated intelligence artefacts
**Git**
Add coacoa/* to .gitignore.
Orchestrator stages changes; you commit/push.
### ⚙ coacoa.yaml — key highlights
```yaml
paths: # where artefacts live
analysis: context/analysis.md
module_map: context/intelligence/module_map.json
build_info: context/intelligence/build_info.json
limits: # token / LOC budgets
max_snippet_loc: 120
max_tokens_context: 12000
workflows:
greenfield: workflows/default_greenfield.yml
brownfield: workflows/default_brownfield.yml
quality:
anti_hallucination: quality/anti_hallucination.md
docs:
adr_dir: docs/adr/ # Architecture Decision Records
file_prefixes:
story: "s_" # s_001_01.md
epic: "e_" # e_001.md
```
(Full schema lives in the file itself.)
## 💬 Command palette (Claude Code / Cline)
| Slash command | Agent invoked | When you use it |
| - | - | - |
| /analyze-codebase | Code-Explorer | First step in brown-field repo |
| /analyst init | Analyst | First step in green-field idea |
| /pm new-prd | PM | Generate / refresh PRD |
| /ux-designer make-ui | UX-Designer | Add UI flows & a11y notes |
| /po refine-epics | Product Owner | Rank epics, create backlog |
| /architect finalize-arch | Architect | Produce architecture doc & ADRs |
| /scrum-master create | Scrum-Master | Split epics into stories |
| /dev implement <story> | Developer | Work a single story |
| /qa review | QA | Validate Dev’s story |
| /orchestrator run | Orchestrator | Drive Dev → QA for next story |
*(Run /orchestrator log anytime to see pipeline status.)*
## 🚀 Green-field walk-through (idea → app)
```text
/analyst init "Real-time expense tracker for remote teams"
/analyst # responds with clarifying questions
→ You answer those questions until ✔ Open-Questions list is empty
/pm new-prd
↳ prd.md + initial epics e_001.md … e_n.md
/ux-designer make-ui
↳ ui_ux.md with wireframes + a11y notes
/po refine-epics
↳ backlog.md (ranked)
/architect finalize-arch
↳ architecture.md + docs/adr/2025-07-26-db-choice.md
/scrum-master create
↳ stories/s_001_01.md …
/orchestrator run
⇒ feature/s_001_01 branch staged
⇒ Dev builds, tests (≥ 90 % coverage), updates story footer
⇒ QA validates, appends report
Human: git commit -m "story s_001_01 – user onboarding" && git push
```
#### Notes
• "/analyst init `"<one-sentence product idea>"` *– You can supply a single-line vision statement inline, or just run /analyst init and paste whatever raw notes you have.*
• The Analyst will always ask follow-up questions until its Open-Questions list is empty; that guarantees the PM starts with a complete domain doc.
• Everything after the Analyst step remains identical to the original workflow.
## 🔧 Brown-field quick-start
```bash
git clone <legacy-repo>
cp -r coacoa/ CLAUDE.md .clinerules .
echo "coacoa/" >> .gitignore
/analyze-codebase # CIS artefacts + build_info.json
/pm new-prd # aligns PRD with real modules
/po refine-epics
/architect finalize-arch # breaks cycles, writes ADR
/scrum-master create
/orchestrator run
```
*Branch rule
Each story = its own branch feature/s_<id> staged only. Humans merge to
trunk after review → zero surprise refactors.*
### ✅ Quality gates snapshot
• Build-Integrity – build, test, lint run before QA (B-1…B-5).
• Coverage – ≥ 90 % lines for touched files; delta tracked in story footer.
• Anti-Hallucination – 12-point symbol & path sanity.
• Arch-Integrity – no dependency cycles, ADRs linked.
• SOLID (pragmatic) – SRP & OCP hard-enforced; others advisory via ADR.
### 🧑🎓 Extending CoaCoA
• Add a new agent: drop agents/<name>.md, reference it in a workflow YAML.
• Add a new quality gate: create checklist in quality/, list it under agent’s checks:.
• Swap LLM: change llm.default in coacoa.yaml.
### 🤔 FAQ
Q: Why no auto-commit?
A: Corporate compliance often requires human sign-off; CoaCoA stages but never commits.
Q: Will stories bloat token context over time?
A: Micro-context is capped to max_snippet_loc (120 LOC); old modules are referenced by path, not pasted.
Q: Can I lower coverage?
A: Yes—set quality.target_coverage in a future release, but 90 % is the sane default for v0.1.
⸻
### ✍ Contributing
1. Fork, branch fix/<topic>.
2. Run /orchestrator run on sample examples/petclinic_py.
3. Ensure all checklists pass.
4. PR with linking ADR if changing architecture.
⸻
**© Licence**
*Apache-2.0 (see LICENSE).*
*Happy shipping! :-)*
Raw data
{
"_id": null,
"home_page": null,
"name": "coacoa",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "cli, developer-tools, code-analysis, software-quality",
"author": null,
"author_email": "Shashank S <procodere@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/9b/10/8d4f9cd0adc2d05f350cffcf8a8a00f91847f3db2d3131248bebb95d6d49/coacoa-0.1.0b1.tar.gz",
"platform": null,
"description": "<!-- README header: paste ABOVE the existing content -->\n\n<p align=\"center\">\n <img src=\".github/banner/CoaCoALogo.png\" alt=\"CoaCoA logo\" width=\"150\">\n</p>\n\n<p align=\"center\">\n <a href=\"https://pypi.org/project/coacoa/\">\n <img src=\"https://img.shields.io/pypi/v/coacoa.svg?color=blue&logo=pypi&label=PyPI%20Version\" alt=\"PyPI\">\n </a>\n <a href=\"https://github.com/im-shashanks/coacoa/blob/main/LICENSE\">\n <img src=\"https://img.shields.io/badge/license-Apache--2.0-green.svg\" alt=\"License\">\n </a>\n <a href=\"https://github.com/im-shashanks/CoaCoA/actions/workflows/ci.yml\">\n <img\n src=\"https://img.shields.io/github/actions/workflow/status/im-shashanks/CoaCoA/ci.yml?branch=main&label=CI%20build\"\n alt=\"CI build status\"\n >\n </a>\n <a href=\"https://codecov.io/gh/im-shashanks/CoaCoA\">\n <img src=\".github/assets/coverage.svg\" alt=\"coverage\">\n </a>\n</p>\n\n# CoaCoA (*v0.1.0b1*)\u2003\u2014\u2003Context aware Coding Assitant\n**Context-Optimised Agentic Coding Assistant** \n- *\u201cDrop it in, branch out, ship confidently.\u201d*\n\n---\n\n## \ud83d\udccc TL;DR \n\n1. `pip install --pre coacoa` *(you can also directly copy the `coacoa/` folder, after git clone `<repo>` if you prefer.)* \n*(--pre flag is required because this is a beta version)* \n\n> \u26a0\ufe0f **Note:** CoaCoA is currently in public beta (`0.1.0b1`). \n> To install, use the `--pre` flag with pip as shown above. \n> The stable release (`0.1.0`) will follow soon. \n\n2. `coacoa init` *(or manual copy) \u2014 scaffolds `coacoa/`, `CLAUDE.md`, `.clinerules`* \n3. `git add . && git commit -m \"init coa\"` \n4. In your IDE (Claude Code / Cline): \n\n ```text\n /analyze-codebase # brown-field \u2502 or \u2502 /analyst init # green-field\n /pm new-prd\n /ux-designer make-ui\n /po refine-epics\n /architect finalize-arch\n /scrum-master create\n /orchestrator run # Dev \u2192 QA loop\n ```\n5. Review staged branch feature/s_001_01, commit & push.\n6. Rinse, repeat \u2192 production-ready PRs with \u2265 90 % test coverage and zero broken builds.\n\n## \ud83c\udfc3\u200d\u2642\ufe0f CLI quick-start\n\n> **Virtual-env:** Create virtualenv `.venv` at the project root `python3 -m venv .venv` \n> All build, test, and lint commands run inside that venv, keeping global Python untouched.\n\n```bash\n# run with explicit sub-command\ncoacoa init --claude-code # scaffold + create CLAUDE.md\n\n# or simply run without a sub-command (same as `init`)\ncoacoa --claude-code\n```\n\n### Getting help\n| Command | Shows\u2026 | \n| - | - | \n| coacoa --help | Global options and the list of sub-commands (init, version, \u2026) | \n| coacoa init --help | The per-command flags: --claude-code, --cline | \n\n-Tip \u2013 Running coacoa with no arguments is equivalent to coacoa init, so you can type the shorter form once you\u2019re familiar with the flags.\n\n### \ud83d\udd27 Configuration \n\u2022 Default settings live in **.coacoa/coacoa.yaml** (ignored by Git). \n\u2022 Create **coacoa.yaml** at project root to override any key; values deep-merge on top of the defaults.\n\n## \u2728 Why CoaCoA?\n| Area | CoaCoA v0.1 | \n| - | - | \n| Config schema | 28-key namespaced YAML | \n| Code-intel | map + deps + complexity + hotspots + coverage + cycles + build_info | \n| Quality gates | \ud83c\udfaf 5 checklists (Anti-Hallucination, Link, QA, Arch, Build) | \n| Workflow | 12 agents (UX, PO, Architect, Code-Explorer, Orchestrator) | \n| Branching | auto feature/<story> branch (staged, not committed) | \n| SOLID policy | Pragmatic SRP/OCP mandatory, rest advisory via ADR | \n\n## \ud83d\uddc2 Folder & file map\ncoacoa/ \n\u251c\u2500 coacoa.yaml \u2190 config (paths, limits, workflows\u2026) \n\u251c\u2500 agents/ \u2190 markdown specs (analyst, pm, \u2026 orchestrator) \n\u251c\u2500 tasks/ \u2190 step-by-step recipes (analyze_codebase.md \u2026) \n\u251c\u2500 templates/ \u2190 PRD, UI/UX, architecture, story, ADR\u2026 \n\u251c\u2500 quality/ \u2190 checklists (anti_hallucination, build_integrity\u2026) \n\u251c\u2500 data/ \u2190 tech_preferences.md, solid_policy.md, style_guides/ \n\u251c\u2500 workflows/ \u2190 default_greenfield.yml, default_brownfield.yml \n\u2514\u2500 context/ \u2190 generated intelligence artefacts \n\n**Git**\nAdd coacoa/* to .gitignore. \nOrchestrator stages changes; you commit/push. \n\n### \u2699 coacoa.yaml \u2014 key highlights\n```yaml\npaths: # where artefacts live\n analysis: context/analysis.md\n module_map: context/intelligence/module_map.json\n build_info: context/intelligence/build_info.json\nlimits: # token / LOC budgets\n max_snippet_loc: 120\n max_tokens_context: 12000\nworkflows:\n greenfield: workflows/default_greenfield.yml\n brownfield: workflows/default_brownfield.yml\nquality:\n anti_hallucination: quality/anti_hallucination.md\ndocs:\n adr_dir: docs/adr/ # Architecture Decision Records\n file_prefixes:\nstory: \"s_\" # s_001_01.md\nepic: \"e_\" # e_001.md\n```\n\n(Full schema lives in the file itself.)\n\n## \ud83d\udcac Command palette (Claude Code / Cline)\n\n| Slash command | Agent invoked | When you use it | \n| - | - | - | \n| /analyze-codebase | Code-Explorer | First step in brown-field repo | \n| /analyst init | Analyst | First step in green-field idea | \n| /pm new-prd | PM | Generate / refresh PRD | \n| /ux-designer make-ui | UX-Designer | Add UI flows & a11y notes | \n| /po refine-epics | Product Owner | Rank epics, create backlog | \n| /architect finalize-arch | Architect | Produce architecture doc & ADRs | \n| /scrum-master create | Scrum-Master | Split epics into stories | \n| /dev implement <story> | Developer | Work a single story | \n| /qa review | QA | Validate Dev\u2019s story | \n| /orchestrator run | Orchestrator | Drive Dev \u2192 QA for next story | \n\n*(Run /orchestrator log anytime to see pipeline status.)* \n\n## \ud83d\ude80 Green-field walk-through (idea \u2192 app)\n\n```text\n/analyst init \"Real-time expense tracker for remote teams\"\n/analyst # responds with clarifying questions\n\u2192 You answer those questions until \u2714 Open-Questions list is empty\n\n/pm new-prd\n \u21b3 prd.md + initial epics e_001.md \u2026 e_n.md\n/ux-designer make-ui\n \u21b3 ui_ux.md with wireframes + a11y notes\n/po refine-epics\n \u21b3 backlog.md (ranked)\n/architect finalize-arch\n \u21b3 architecture.md + docs/adr/2025-07-26-db-choice.md\n/scrum-master create\n \u21b3 stories/s_001_01.md \u2026\n/orchestrator run\n \u21d2 feature/s_001_01 branch staged\n \u21d2 Dev builds, tests (\u2265 90 % coverage), updates story footer\n \u21d2 QA validates, appends report\nHuman: git commit -m \"story s_001_01 \u2013 user onboarding\" && git push\n``` \n\n#### Notes\n\u2022\t\"/analyst init `\"<one-sentence product idea>\"` *\u2013 You can supply a single-line vision statement inline, or just run /analyst init and paste whatever raw notes you have.* \n\u2022\tThe Analyst will always ask follow-up questions until its Open-Questions list is empty; that guarantees the PM starts with a complete domain doc. \n\u2022\tEverything after the Analyst step remains identical to the original workflow. \n\n## \ud83d\udd27 Brown-field quick-start\n\n```bash\ngit clone <legacy-repo>\ncp -r coacoa/ CLAUDE.md .clinerules .\necho \"coacoa/\" >> .gitignore\n/analyze-codebase # CIS artefacts + build_info.json\n/pm new-prd # aligns PRD with real modules\n/po refine-epics\n/architect finalize-arch # breaks cycles, writes ADR\n/scrum-master create\n/orchestrator run\n```\n\n*Branch rule \nEach story = its own branch feature/s_<id> staged only. Humans merge to \ntrunk after review \u2192 zero surprise refactors.* \n\n### \u2705 Quality gates snapshot\n\u2022\tBuild-Integrity \u2013 build, test, lint run before QA (B-1\u2026B-5). \n\u2022\tCoverage \u2013 \u2265 90 % lines for touched files; delta tracked in story footer. \n\u2022\tAnti-Hallucination \u2013 12-point symbol & path sanity. \n\u2022\tArch-Integrity \u2013 no dependency cycles, ADRs linked. \n\u2022\tSOLID (pragmatic) \u2013 SRP & OCP hard-enforced; others advisory via ADR. \n\n### \ud83e\uddd1\u200d\ud83c\udf93 Extending CoaCoA\n\u2022\tAdd a new agent: drop agents/<name>.md, reference it in a workflow YAML. \n\u2022\tAdd a new quality gate: create checklist in quality/, list it under agent\u2019s checks:. \n\u2022\tSwap LLM: change llm.default in coacoa.yaml. \n\n### \ud83e\udd14 FAQ\n\nQ: Why no auto-commit? \nA: Corporate compliance often requires human sign-off; CoaCoA stages but never commits. \n\nQ: Will stories bloat token context over time? \nA: Micro-context is capped to max_snippet_loc (120 LOC); old modules are referenced by path, not pasted. \n\nQ: Can I lower coverage? \nA: Yes\u2014set quality.target_coverage in a future release, but 90 % is the sane default for v0.1. \n\n\u2e3b\n\n### \u270d Contributing\n1.\tFork, branch fix/<topic>. \n2.\tRun /orchestrator run on sample examples/petclinic_py. \n3.\tEnsure all checklists pass. \n4.\tPR with linking ADR if changing architecture. \n\n\u2e3b\n\n**\u00a9 Licence**\n\n*Apache-2.0 (see LICENSE).*\n\n*Happy shipping! :-)*\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Context-Optimised Agentic Coding Assistant",
"version": "0.1.0b1",
"project_urls": null,
"split_keywords": [
"cli",
" developer-tools",
" code-analysis",
" software-quality"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8b95ac038dc3d25c10694f44632a9b651077bf9f1137988f57f17ea30efb1aeb",
"md5": "2e94f7469341f4ba765051e1aa1254d9",
"sha256": "c1682d2efc46f8e8ee9e505413c19350dc3fda3783834cd11aeb4b1cd5513786"
},
"downloads": -1,
"filename": "coacoa-0.1.0b1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2e94f7469341f4ba765051e1aa1254d9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 52434,
"upload_time": "2025-07-27T22:59:42",
"upload_time_iso_8601": "2025-07-27T22:59:42.205218Z",
"url": "https://files.pythonhosted.org/packages/8b/95/ac038dc3d25c10694f44632a9b651077bf9f1137988f57f17ea30efb1aeb/coacoa-0.1.0b1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9b108d4f9cd0adc2d05f350cffcf8a8a00f91847f3db2d3131248bebb95d6d49",
"md5": "5829841bfc0bae1e0fb7eb73cd8f4c4a",
"sha256": "126c91b08bd9d964986e98b0844ff44810d271979d2de91fe4c9a4049029536b"
},
"downloads": -1,
"filename": "coacoa-0.1.0b1.tar.gz",
"has_sig": false,
"md5_digest": "5829841bfc0bae1e0fb7eb73cd8f4c4a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 43965,
"upload_time": "2025-07-27T22:59:43",
"upload_time_iso_8601": "2025-07-27T22:59:43.606352Z",
"url": "https://files.pythonhosted.org/packages/9b/10/8d4f9cd0adc2d05f350cffcf8a8a00f91847f3db2d3131248bebb95d6d49/coacoa-0.1.0b1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-27 22:59:43",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "coacoa"
}
JSON