codo-ai 2.23.14 → 2.23.15

package/README.md

@@ -1,119 +1,225 @@
-<div align="center">
-
-# \>_ COdo
-
-**The security-native AI coding agent.**
-
-Spec it. Code it. Ship it. **Secure it.**
-
-[Website](https://codo-ai.vercel.app/) · [Documentation](https://codo-ai.vercel.app/) · [GitHub](https://github.com/Mosalah4351/COdo) · [Report Issue](https://github.com/Mosalah4351/COdo/issues)
-
-`npm install -g codo-ai`
-
-</div>
-
----
-
-## What is COdo?
-
-COdo is a **terminal-native, spec-driven AI coding agent** — a fork of [OpenCode](https://github.com/anomalyco/opencode) with structured workflow orchestration, an autonomous multi-agent compose engine, and the all-new **Sec-Test** red security engine.
-
-No browser tab. No separate app. No context-switching. Just you, your terminal, and an AI that knows what phase of the project you're in.
-
-```
-$ npm install -g codo-ai
-$ cd my-project
-$ codo
-```
-
-## Why COdo?
-
-| | Static linters | CI scanners | **COdo Sec-Test** |
-|---|---|---|---|
-| Finds design flaws pre-code | ✗ | ✗ | ✓ STRIDE threat modeling |
-| Noise level | False-positive flood | Late-stage flood | Evidence-first findings w/ PoC |
-| Runs where you work | ✗ | CI only | ✓ Your terminal |
-| Fixes vulnerabilities | Warnings only | Warnings only | ✓ Remediation diffs + mutation-backed tests |
-
-## Highlights
-
-### Sec-Test — Autonomous Security Orchestrator
-Six specialist personas guarding the full lifecycle:
-
-| Persona | Role |
-|---|---|
-| **Security Architect** | Pre-code STRIDE/DREAD threat modeling (OWASP ASVS mapped) |
-| **AppSec Engineer** | Real-time SAST on diffs — OWASP Top 10:2025 / CWE Top 25, secrets, CVEs |
-| **DevSecOps Engineer** | Pipeline hardening (NIST SSDF), SBOM (CycloneDX/SPDX), SLSA + Sigstore |
-| **Penetration Tester** | Scope-gated live probing (PTES/WSTG) — refuses targets outside `.codo/security-scope.json` |
-| **Quality Engineer** | Adversarial tests verified by mutation kill-rate |
-| **Security Engineer** | Audits the agent itself; posture drift tracking |
-
-```bash
-$ /sec-test "Audit git diff for SQL injection and hardcoded secrets"
-[1] Raw string concatenation in query builder
-[2] Hardcoded fallback JWT secret ("dev-secret-key-12345")
-→ Parameterized query fix applied · secret moved to env with startup validation
-```
-
-### Workflow Engines
-Switch methodology per project scale:
-
-- `/workflow gsd` — autonomous milestone planning, persistent `.planning/` state, survives context resets
-- `/workflow gstack` — Garry Tan's 23-role virtual engineering team
-- `/workflow speckit` — GitHub SDD spec-first pipeline
-- `/workflow vibemode` — pure flow, zero overhead
-
-### Multi-Agent Compose
-Complex tasks decompose into DAGs routed to specialist agents executing in parallel waves:
-
-```
-/compose "Build auth service with JWT, rate limiting & Sec-Test"
-  [A] Security Architect → threat model        ┐ parallel
-  [B] Builder            → implementation       ├ wave
-  [C] AppSec Engineer    → real-time SAST audit │
-  [D] Quality Engineer   → mutation tests       ┘
-```
-
-### Goal Judge
-Declare outcomes, not tasks. An independent judge model verifies stop-conditions — the builder never self-approves.
-
-```
-/goal "All tests pass with >80% coverage and zero HIGH/CVEs"
-```
-
-### Business Suite
-Production-grade office tooling as skills: `xlsx-official`, `docx-official`, `pptx-official`, `pdf-official`, `deep-research`, `super-research`, `research-paper-writing`, `html-to-video-pipeline`, `sales`.
-
-### Compliance-First Scraper
-`/scraper <url> <what to extract>` — robots.txt honored, ToS checked, crawl-delays enforced, escalation ladder from static fetch to authenticated sessions.
-
-## Install
-
-```bash
-# Recommended
-npm install -g codo-ai
-
-# One-time run
-npx codo-ai
-```
-
-Requirements: Node 18+ or Bun · macOS / Linux / Windows · any provider API key (Anthropic, OpenAI, NVIDIA free tier, Google, or OpenAI-compatible).
-
-> No extra flags needed: the install works out of the box even when install scripts are blocked (`allowScripts` policies, `--ignore-scripts`), because the launcher resolves the prebuilt platform binary automatically on first run.
-
-> Migrating from `@codo-ai/cli`? That package is deprecated — `codo-ai` replaces it.
-
-## Documentation
-
-Full developer docs — every persona, skill, workflow, permission mode, and best practice — live at **[codo-ai.vercel.app](https://codo-ai.vercel.app/)**.
-
-## Contributing
-
-PRs welcome on [GitHub](https://github.com/Mosalah4351/COdo). Default branch: `dev`. Conventional commits.
-
-## License
-
-MIT © [Mohamed Salah](https://www.linkedin.com/in/mohamed-salah-59bb41300/)
-
-Built on [OpenCode](https://github.com/anomalyco/opencode).
+<div align="center">
+
+# \>_ COdo
+
+**Spec-Driven Software Development with Security-Guided Multi-Agent Orchestration**
+
+Spec it. Code it. Ship it. **Secure it.**
+
+[Website](https://codo-ai.vercel.app/) | [Documentation](https://codo-ai.vercel.app/) | [GitHub](https://github.com/Mosalah4351/COdo) | [Report Issue](https://github.com/Mosalah4351/COdo/issues)
+
+`npm install -g codo-ai`
+
+**Latest release: 2.23.15**
+
+</div>
+
+---
+
+## What's new in 2.23.15
+
+- **Sensei** - a senior technical advisor you can consult mid-task. Read-only, evidence-first, and it ends every verdict with a decisive recommendation.
+- **Checker** - a quality and hygiene auditor that verifies findings against real evidence and records them durably instead of guessing.
+- **Business Agent** - an orchestrator with hands that turns requests into real `.xlsx`, `.docx`, `.pptx`, `.pdf`, and research deliverables.
+- **`/ask-sensei`, `/quality-check`, `/hygiene-check`** - three new commands that dispatch those specialists in one keystroke.
+- **`sensei_model` / `judge_model` / `subagent_model`** - put your strongest model where judgment matters and a cheap one where it does not.
+- **Free to start** - OpenCode Zen free models, OpenRouter `:free` variants, and NVIDIA's free tier all work out of the box.
+
+## What is COdo?
+
+COdo is a **terminal-native, spec-driven AI coding agent** - a fork of [OpenCode](https://github.com/anomalyco/opencode) with structured workflow orchestration, an autonomous multi-agent compose engine, a built-in advisory layer, and the all-new **Sec-Test** red security engine.
+
+No browser tab. No separate app. No context-switching. Just you, your terminal, and an AI that knows what phase of the project you're in.
+
+```
+$ npm install -g codo-ai
+$ cd my-project
+$ codo
+```
+
+## Sensei - the second opinion your agent was missing
+
+Most agents grade their own homework. COdo ships a **Sensei**: a read-only senior advisor that reads the actual conversation - the request, every dispatch, every tool result - and tells the agent what it would do differently.
+
+```
+/ask-sensei "is this migration safe to ship?"
+```
+
+The Sensei does not guess. It inspects files, git history, configs, and command output first, cites what it saw, names the trade-offs, and commits to a call. Every response ends in a fixed verdict block:
+
+```
+## SENSEI
+- Assessment: the migration is reversible but the backfill is not
+- Risks: 40k rows rewritten in one transaction; lock held for ~90s
+- Recommendation: batch by 5k with a resumable cursor before shipping
+- Confidence: high - measured against the actual migration file
+```
+
+It is also wired in as **automatic escalation**: primary agents are instructed to consult it before committing to an approach, when stuck on a repeated failure, before dropping an agreed plan, and before declaring work done.
+
+## Choose your models
+
+You are not stuck with one model. COdo exposes three independent knobs, so you can spend your strongest model only where judgment matters:
+
+| Key | Drives | A sensible fit |
+|---|---|---|
+| `sensei_model` | the Sensei (`/ask-sensei`) **and** the Checker (`/quality-check`, `/hygiene-check`) | your strongest reasoning model |
+| `judge_model` | the Goal Judge that verifies stop-conditions | a solid mid-tier model |
+| `subagent_model` | every dispatched subagent and parallel compose worker | a fast, cheap model |
+
+```jsonc
+{
+  "sensei_model": "anthropic/claude-opus-4#high",
+  "judge_model": "anthropic/claude-sonnet-4",
+  "subagent_model": "anthropic/claude-haiku-4"
+}
+```
+
+`sensei_model` falls back to `judge_model`, then to the standard subagent chain. Any of the three can point at a free model, so a fully free setup is a valid configuration.
+
+### Free models - run COdo without a bill
+
+COdo is provider-agnostic, and several providers give you usable capacity for nothing:
+
+- **OpenCode Zen free models** - sign in once and pick a free-tier model such as `Big Pickle`, `Ox Alpha Free`, `MiMo-V2.5 Free`, `Hy3 Free`, `Nemotron 3 Ultra Free`, `Nemotron 3.5 Lightning Free`, or `Muse Spark 1.2 Contributor Free`. Good enough to drive a real coding session, and the fastest way to try COdo.
+- **OpenRouter** - use any `:free` model variant with your OpenRouter key. Great for mixing providers behind one endpoint.
+- **NVIDIA** - a free-tier API key from `build.nvidia.com` gives you NVIDIA-hosted models at no cost.
+
+Point `subagent_model` at a free model to keep the fan-out cheap, and reserve a stronger `sensei_model` for the moments that decide how the work turns out.
+
+## Checker - ship-readiness, verified
+
+`/quality-check` and `/hygiene-check` dispatch the **Checker**, a read-only auditor for bugs, security issues, code-quality problems, and repo hygiene: committed secrets, tracked junk, dead weight, risky code with no tests.
+
+The Checker refuses to report what it cannot prove. Every finding needs a file and line or a tool-output snippet, and confirmed findings are written to a durable findings store so they survive the session, feed posture reports, and can be exported as SARIF.
+
+```bash
+$ /quality-check "review the last commit"
+[high] src/db/query.ts:42 - raw string concatenation in SQL builder (CWE-89)
+[low]  tracked artifact: server.log committed at repo root
+summary: 1 high, 1 low - fix the query builder first
+```
+
+## Why COdo?
+
+| | Static linters | CI scanners | **COdo Sec-Test** |
+|---|---|---|---|
+| Finds design flaws pre-code | no | no | **yes - STRIDE threat modeling** |
+| Noise level | false-positive flood | late-stage flood | **evidence-first findings with PoC** |
+| Runs where you work | no | CI only | **your terminal** |
+| Fixes vulnerabilities | warnings only | warnings only | **remediation diffs + mutation-backed tests** |
+
+## Highlights
+
+### Sec-Test - Autonomous Security Orchestrator
+
+Six specialist personas guarding the full lifecycle:
+
+| Persona | Role |
+|---|---|
+| **Security Architect** | Pre-code STRIDE/DREAD threat modeling (OWASP ASVS mapped) |
+| **AppSec Engineer** | Real-time SAST on diffs - OWASP Top 10:2025 / CWE Top 25, secrets, CVEs |
+| **DevSecOps Engineer** | Pipeline hardening (NIST SSDF), SBOM (CycloneDX/SPDX), SLSA + Sigstore |
+| **Penetration Tester** | Scope-gated live probing (PTES/WSTG) - refuses targets outside `.codo/security-scope.json` |
+| **Quality Engineer** | Adversarial tests verified by mutation kill-rate |
+| **Security Engineer** | Audits the agent itself; posture drift tracking |
+
+```bash
+$ /sec-test "Audit git diff for SQL injection and hardcoded secrets"
+[1] Raw string concatenation in query builder
+[2] Hardcoded fallback JWT secret ("dev-secret-key-12345")
+-> Parameterized query fix applied; secret moved to env with startup validation
+```
+
+### Workflow Engines
+
+Switch methodology per project scale:
+
+- `/workflow gsd` - autonomous milestone planning, persistent `.planning/` state, survives context resets
+- `/workflow gstack` - Garry Tan's 23-role virtual engineering team
+- `/workflow speckit` - GitHub SDD spec-first pipeline
+- `/workflow vibemode` - pure flow, zero overhead
+
+### Multi-Agent Compose
+
+Complex tasks decompose into DAGs routed to specialist agents executing in parallel waves:
+
+```
+/compose "Build auth service with JWT, rate limiting & Sec-Test"
+  [A] Security Architect  -> threat model          | parallel
+  [B] Builder             -> implementation        | wave
+  [C] AppSec Engineer     -> real-time SAST audit  |
+  [D] Quality Engineer    -> mutation tests        |
+```
+
+### Goal Judge
+
+Declare outcomes, not tasks. An independent judge model verifies stop-conditions - the builder never self-approves.
+
+```
+/goal "All tests pass with >80% coverage and zero HIGH/CVEs"
+```
+
+## Business Agent - deliverables, not chat
+
+COdo ships a dedicated **Business Agent**: an orchestrator with hands. It routes each request to the right `business:*` skill and then *does the work itself* - writing the scripts, running them, and handing you real files on disk, verified before handoff.
+
+```bash
+$ codo
+> research the 2026 AI agent market and give me a deck plus a one-pager PDF
+Plan: research -> deck -> one-pager PDF
+[deep-research]   14 sources, cited
+[pptx-official]   market-overview.pptx  (12 slides)
+[pdf-official]    market-overview.pdf   (2 pages)
+```
+
+It chains skills for multi-deliverable requests and picks the most probable one when a request is ambiguous, stating its choice in a line instead of stalling.
+
+| Ask for | It produces |
+|---|---|
+| Spreadsheet models, cleanup, formulas, exports | `.xlsx` / `.csv` via `xlsx-official` |
+| Reports, letters, contracts, templates | `.docx` via `docx-official` |
+| Slide decks and presentations | `.pptx` via `pptx-official` |
+| PDF creation, form filling, OCR, merge/split | `.pdf` via `pdf-official` |
+| Multi-source investigation with citations | cited report via `deep-research` |
+| Long-running autonomous research and experiments | evidence-backed study via `super-research` |
+| Academic papers, LaTeX, citation audits | publication-ready paper via `research-paper-writing` |
+| KPIs, dashboards, charts, metric diagnostics | analysis + charts via `data-analytics` |
+| Design specs, UI and product design | `design-blueprint`, `frontend-design`, `product-design` |
+| Courses, sales material, video renders, skill authoring | `learn-everything`, `sales`, `html-to-video-pipeline`, `skill-creator` |
+
+## Compliance-First Scraper
+
+`/scraper <url> <what to extract>` - robots.txt honored, ToS checked, crawl-delays enforced, escalation ladder from static fetch to authenticated sessions.
+
+## Install
+
+```bash
+# Recommended
+npm install -g codo-ai
+
+# One-time run
+npx codo-ai
+```
+
+Requirements: Node 18+ or Bun | macOS / Linux / Windows | any provider - bring an Anthropic, OpenAI, Google, or OpenAI-compatible key, or start free on OpenCode Zen, OpenRouter, or NVIDIA.
+
+> Migrating from `@codo-ai/cli`? That package is deprecated - `codo-ai` replaces it.
+
+## Documentation
+
+Full developer docs - every persona, skill, workflow, permission mode, and best practice - live at **[codo-ai.vercel.app](https://codo-ai.vercel.app/)**.
+
+## Contributing
+
+PRs welcome on [GitHub](https://github.com/Mosalah4351/COdo). Default branch: `dev`. Conventional commits.
+
+## License
+
+MIT (c) [Mohamed Salah](https://www.linkedin.com/in/mohamed-salah-59bb41300/)
+
+Built on [OpenCode](https://github.com/anomalyco/opencode).
+
+---
+
+<sub>**Search terms:** spec-driven development, security-guided multi-agent orchestration, AI coding agent, terminal AI agent, CLI coding assistant, agentic coding, autonomous coding agent, multi-agent orchestration, subagents, sensei, second opinion, AI code review, AI security scanner, AppSec, SAST, DAST, threat modeling, penetration testing, OWASP Top 10, CWE Top 25, SBOM, SLSA, Sigstore, secrets scanning, mutation testing, SDD, GSD workflow, Spec Kit, business agent, deep research agent, web scraper, xlsx, docx, pptx, pdf, MCP, Model Context Protocol, provider agnostic, free AI coding agent, free models, OpenCode Zen, OpenRouter, OpenAI, Anthropic, Claude, Gemini, NVIDIA, Ollama, OpenCode alternative, Claude Code alternative, Cursor alternative, Copilot alternative, Node.js, Bun, TypeScript, Windows, macOS, Linux, latest release.</sub>

package/package.json

@@ -1,27 +1,95 @@
 {
   "name": "codo-ai",
-  "description": "The security-native AI coding agent. Six Sec-Test security personas, compliance-first /scraper, a business documents & research suite, and multi-agent Compose orchestration — spec-driven workflow engines in one terminal-first CLI.",
+  "description": "Spec-driven software development with security-guided multi-agent orchestration. Terminal AI coding agent with a Sensei second opinion, a Checker, six Sec-Test security personas, a Business Agent for xlsx/docx/pptx/pdf deliverables, and free-model support.",
   "keywords": [
     "ai",
     "ai-agent",
+    "ai-coding-agent",
     "coding-agent",
     "coding-assistant",
-    "cli",
+    "agentic",
+    "agentic-coding",
+    "autonomous-agent",
+    "multi-agent",
+    "multi-agent-orchestration",
+    "orchestration",
+    "subagents",
+    "sensei",
+    "second-opinion",
+    "judge",
+    "checker",
+    "business-agent",
+    "spec-driven",
+    "spec-driven-development",
+    "sdd",
+    "gsd",
+    "speckit",
+    "workflow",
     "terminal",
+    "terminal-ui",
     "tui",
+    "cli",
     "llm",
+    "code-generation",
+    "code-review",
+    "pair-programming",
+    "developer-tools",
+    "devtools",
+    "devtool",
     "security",
-    "sast",
+    "security-scanner",
+    "security-audit",
     "appsec",
     "devsecops",
+    "sast",
+    "dast",
     "threat-modeling",
     "pentest",
-    "spec-driven",
-    "multi-agent",
-    "autonomous",
+    "penetration-testing",
+    "vulnerability-scanner",
+    "owasp",
+    "cwe",
+    "sbom",
+    "slsa",
+    "sigstore",
+    "secrets-scanning",
+    "compliance",
+    "quality-assurance",
+    "testing",
+    "mutation-testing",
+    "research",
+    "deep-research",
+    "scraper",
+    "web-scraping",
+    "xlsx",
+    "docx",
+    "pptx",
+    "pdf",
     "mcp",
-    "devtools",
-    "opencode"
+    "model-context-protocol",
+    "provider-agnostic",
+    "free-models",
+    "free-ai",
+    "opencode-zen",
+    "openrouter",
+    "openai",
+    "anthropic",
+    "claude",
+    "gemini",
+    "nvidia",
+    "ollama",
+    "opencode",
+    "opencode-alternative",
+    "claude-code-alternative",
+    "cursor-alternative",
+    "copilot-alternative",
+    "nodejs",
+    "bun",
+    "typescript",
+    "windows",
+    "macos",
+    "linux",
+    "latest"
   ],
   "engines": {
     "node": ">=18"
@@ -37,7 +105,7 @@
   "bin": {
     "codo": "./bin/codo.js"
   },
-  "version": "2.23.14",
+  "version": "2.23.15",
   "license": "MIT",
   "os": [
     "darwin",
@@ -49,17 +117,17 @@
     "x64"
   ],
   "optionalDependencies": {
-    "@codo-ai/codo-windows-x64-baseline": "2.23.14",
-    "@codo-ai/codo-windows-x64": "2.23.14",
-    "@codo-ai/codo-windows-arm64": "2.23.14",
-    "@codo-ai/codo-linux-x64-musl": "2.23.14",
-    "@codo-ai/codo-linux-x64-baseline-musl": "2.23.14",
-    "@codo-ai/codo-linux-x64-baseline": "2.23.14",
-    "@codo-ai/codo-linux-x64": "2.23.14",
-    "@codo-ai/codo-linux-arm64-musl": "2.23.14",
-    "@codo-ai/codo-linux-arm64": "2.23.14",
-    "@codo-ai/codo-darwin-x64-baseline": "2.23.14",
-    "@codo-ai/codo-darwin-x64": "2.23.14",
-    "@codo-ai/codo-darwin-arm64": "2.23.14"
+    "@codo-ai/codo-windows-x64-baseline": "2.23.15",
+    "@codo-ai/codo-windows-x64": "2.23.15",
+    "@codo-ai/codo-windows-arm64": "2.23.15",
+    "@codo-ai/codo-linux-x64-musl": "2.23.15",
+    "@codo-ai/codo-linux-x64-baseline-musl": "2.23.15",
+    "@codo-ai/codo-linux-x64-baseline": "2.23.15",
+    "@codo-ai/codo-linux-x64": "2.23.15",
+    "@codo-ai/codo-linux-arm64-musl": "2.23.15",
+    "@codo-ai/codo-linux-arm64": "2.23.15",
+    "@codo-ai/codo-darwin-x64-baseline": "2.23.15",
+    "@codo-ai/codo-darwin-x64": "2.23.15",
+    "@codo-ai/codo-darwin-arm64": "2.23.15"
   }
 }