Cortex AI

Stop re-explaining your codebase. Start shipping.
_{19 specialized subagents · 11 slash commands · Persistent memory via Obsidian · Four-layer architecture · pre-commit enforcement}

Quick Start · Architecture · Subagents · Commands · FAQ

_{For solo developers, small teams, and AI-first engineering workflows.}

---

"Claude went from a copilot I had to babysit to a staff engineer that knows my entire architecture. Context setup took 10 minutes — it's been compounding ever since."

---

The Problem

Every Claude Code session starts from zero. Claude doesn't remember your architecture, your conventions, or the decisions you made last week. You waste the first 10 minutes re-explaining context — every single time.

This template fixes that.

Without this template	With this template
❌ Re-explain architecture every session	✅ Claude reads CLAUDE.md + CONTEXT.md in 30 seconds
❌ Inconsistent code quality across sessions	✅ 19 expert subagents enforce domain-specific standards
❌ Decisions lost between sessions	✅ ADRs + Obsidian vault preserve institutional knowledge
❌ "Just code it" → wrong problem solved correctly	✅ /plan forces structured thinking before implementation
❌ Ship and pray	✅ /ship runs automated code review before every commit

---

✨ Key Features

🧩 19 Expert Subagents Specialized AI personas in three tiers — Leadership (tech-lead, product-manager), Execution (12 domain specialists), and Quality/Meta (tech-debt-hunter, release-manager, research-analyst, prompt-engineer). No context contamination between tasks.	🗂️ Zero Context Loss CLAUDE.md + CONTEXT.md + Obsidian vault give Claude full project context from session one. Your institutional knowledge compounds over time, not resets.
⚡ 11 Slash Commands /plan → /review → /ship plus /audit, /research, /release — a complete development lifecycle from requirements to release validation.	🔧 Pre-commit Enforcement Automatic formatting (ruff, prettier, sqlfluff), secrets scanning (gitleaks), Conventional Commits (commitlint), and markdown linting — enforced on every commit, not just in CI.
📐 Architecture Decision Records /adr captures every significant decision in MADR format. Future engineers (and future Claude sessions) know why, not just what.	🧠 Second Brain (Obsidian) Session logs, decision copies, and cross-project patterns sync to a single Obsidian vault. Knowledge persists across all your projects.

---

🏗️ Architecture

The template is organized in four layers, each solving a different problem:

graph TD
    subgraph L1["① Second Brain — Persistent Memory"]
        OV["Obsidian Vault<br/>~/vault/"]
        GL["Global CLAUDE.md<br/>~/.claude/CLAUDE.md"]
    end

    subgraph L2["② Project Context — Session Bootstrap"]
        CM["CLAUDE.md<br/>Project identity & conventions"]
        CTX["CONTEXT.md<br/>Live session state"]
        ADR["docs/adr/<br/>Decision log"]
        GR["graphify-out/<br/>Code knowledge graph"]
    end

    subgraph L3["③ Agent Layer — Domain Expertise"]
        AG["19 Subagents<br/>.claude/agents/"]
        CMD["11 Commands<br/>.claude/commands/"]
        SK["4 Skills + 7 Rules<br/>.claude/skills/ + .claude/rules/"]
    end

    subgraph L4["④ Execution — Automation"]
        HK["5 Hooks<br/>.claude/hooks/"]
        CF["settings.json<br/>Permissions allowlist"]
        CI[".github/workflows/<br/>CI/CD"]
        PC[".pre-commit-config.yaml<br/>Local enforcement"]
    end

    L1 -->|"persists across repos"| L2
    L2 -->|"informs task routing"| L3
    L3 -->|"executes via"| L4

Loading

Layer	What it does	Changes how often
① Second Brain	Memory across all projects (Obsidian vault + global CLAUDE.md)	Slowly — accumulates over months
② Project Context	Per-project knowledge Claude reads at session start	Per session — CONTEXT.md is mutable
③ Agent Layer	Specialized AI personas + slash commands + skills	Rarely — stable once configured
④ Execution	Hooks, permissions, CI/CD — runs automatically	Set once, forget

📖 Full architecture documentation: docs/architecture.md

🔬 Deep Dive: The Context Engine — Graphify × Obsidian

The two optional integrations serve fundamentally different purposes:

	🕸️ Graphify	🧠 Obsidian
Role	The Navigation Map	The Strategic Brain
Focus	Topology & discovery	History & decisions
What it does	Builds a dependency graph from your code. Before Claude reads any file, it reads the Graphify report and already knows where things are.	Persists session logs, ADR copies, and cross-project patterns. When you return after 3 months, Claude knows why you made that decision.
Token impact	Eliminates expensive grep searches — Claude goes directly to the right file	Prevents re-debating settled decisions — Claude won't suggest refactoring something you already decided to keep
Vibe	Architectural Awareness	Institutional Knowledge

While Graphify tells Claude where things are (Spatial Context), Obsidian tells Claude why things are (Historical Context). Together, they eliminate the "blank slate" problem of LLMs.

Both are optional. The template works without either. But together, they transform Claude from a stateless tool into a context-aware engineering partner.

---

⚡ 2-Minute Setup

Step 1. Clone and init:

git clone https://github.com/GabrielHenriqueCA/cortex-ai.git my-project
cd my-project && rm -rf .git && git init

Step 2. Open Claude Code:

claude .

Step 3. Type inside Claude Code:

/setup

That's it. Claude will auto-detect your OS, install missing formatters (ruff, prettier), create your Obsidian vault, bootstrap the Graphify knowledge graph, and configure everything — zero manual config.

💡 Prefer doing it yourself? Run bash setup.sh in your terminal — same result, no Claude needed. 📋 Just checking status? bash setup.sh --check (dry-run, no installs).

---

🚀 Full Quick Start

Step-by-step setup with Graphify and Obsidian

1. Clone the template

git clone https://github.com/GabrielHenriqueCA/cortex-ai.git my-project
cd my-project

2. Start fresh git history

rm -rf .git && git init
git add . && git commit -m "chore: initialize from cortex-ai"

3. Configure your project identity

Open CLAUDE.md and replace the three placeholders:

# Project: <PROJECT_NAME>        →  # Project: My Awesome API
> **Stack:** <STACK>              →  > **Stack:** Python 3.12, FastAPI, PostgreSQL
> **Status:** <STATUS>            →  > **Status:** Early development

4. Open Claude Code

claude .

That's it. Your first session starts with full architectural context.

Optional: Install Graphify

pip install graphify
graphify init . && graphify build .

Graphify gives Claude architecture context before reading files. It's completely optional — every template feature works without it. The hooks check for the binary first and skip silently if not found.

Optional: Set up Obsidian vault

mkdir -p ~/vault/projects/<your-project-name>/sessions
mkdir -p ~/vault/projects/<your-project-name>/decisions

📖 Full setup guide: docs/obsidian-vault-setup.md

---

🤖 Subagents

Each subagent is a specialized AI persona with its own workflow, output format, and hard rules. They start fresh with exactly the expertise needed — no accumulated noise from unrelated tasks. The 19 agents are organized in three tiers:

graph TD
    subgraph LEAD["🎯 Leadership — Start here for complex work"]
        TL["tech-lead\nOrchestrates + decomposes"]
        PM["product-manager\nRequirements + acceptance criteria"]
    end
    subgraph EXEC["⚙️ Execution — Domain specialists"]
        direction LR
        AR["architect"] & CR["code-reviewer"] & DB["debugger"]
        RF["refactor"] & TW["test-writer"] & FE["frontend"]
        BE["backend"] & DE["data-engineer"] & ML["ml-engineer"]
        DW["docs-writer"] & DO["devops"]
    end
    subgraph QUAL["🔍 Quality & Meta"]
        TDH["tech-debt-hunter"] & RM["release-manager"]
        SA["security-auditor"] & PF["performance"]
        RA["research-analyst"] & PE["prompt-engineer"]
    end
    TL -->|routes| EXEC
    TL -->|routes| QUAL
    PM -->|feeds criteria| EXEC

Loading

Leadership Layer

Agent	Role	When to Use
🎯 tech-lead	Decomposes complex tasks, routes to the right agents, parallelizes independent work	Any task touching multiple domains
📋 product-manager	Translates vague requests into testable acceptance criteria and edge cases	Before any feature implementation

Execution Layer

Agent	Role	When to Use
🏛️ architect	System design, trade-off analysis (never writes code)	Starting a feature, evaluating tech choices
🔍 code-reviewer	Opinionated PR review (🔴/🟡/🟢 labels)	Before every merge
🐛 debugger	Scientific root cause investigation	Unexpected errors, intermittent failures
♻️ refactor	Surgical code restructuring (zero behavior change)	Code smells, untestable structure
🧪 test-writer	TDD-focused, AAA pattern, edge cases first	New behavior, coverage gaps
🔮 data-engineer	Databricks, dbt, Delta Lake, data contracts	Pipeline design, SQL review
🤖 ml-engineer	ML experiment design, leakage prevention	Model development, evaluation
🎨 frontend	React/TypeScript, accessibility-first	UI components, state management
⚙️ backend	APIs, auth, observability	Service design, endpoint review
📝 docs-writer	Example-driven, outcome-oriented docs	READMEs, runbooks, API docs
🐳 devops	CI/CD, Docker, IaC, observability	Deploy pipelines, infra-as-code

Quality & Meta Layer

Agent	Role	When to Use
🔎 tech-debt-hunter	Full codebase audit — quantified debt inventory	Start of quarter, velocity declining
🚀 release-manager	Pre-merge validation, CHANGELOG, version bump, release notes	Before every merge to main
🛡️ security-auditor	OWASP Top 10, threat modeling	Pre-release, auth/secrets changes
📊 performance	Profiler-driven optimization (measure first)	Latency regressions, slow queries
🔬 research-analyst	Evidence-based technology comparison (3+ candidates)	Choosing libraries, build vs buy
🧠 prompt-engineer	Diagnoses and rewrites underperforming agents	When an agent produces weak output

Example: How the architect agent works

Workflow: Clarify scope → audit existing architecture → identify constraints → generate 2–3 options → evaluate trade-offs → recommend with rationale → produce Mermaid diagram + interface contracts.

Hard rule: Never writes code. Produces diagrams, specs, and decision rationale only.

Output: Structured comparison with named options, explicit recommendation, first irreversible decision identified.

Anti-patterns it flags:

• Premature microservices decomposition on a team of < 5
• Distributed monolith disguised as "microservices"
• Event-driven everything without clear consistency requirements
• Caching layered over a broken data model

Example: How the code-reviewer agent works

Labels: 🔴 BLOCKER (must fix) · 🟡 SHOULD (strong recommendation) · 🟢 NIT (take it or leave it)

Hard rules: Every comment has a label. Every 🔴 and 🟡 explains the risk. Redundant comments are always flagged as a blocker.

Anti-patterns it flags:

• pass in exception handlers without logging
• Bare except: catching BaseException
• Magic numbers without named constants
• Boolean parameter traps (process(data, True, False))
• SQL string formatting instead of parameterized queries
• Business logic in view/controller layer

📖 Full agent specifications: .claude/agents/

---

⚡ Slash Commands

Command	What It Does
/setup	Diagnose & fix environment — checks tools, vault, and graph, installs what's missing
/plan	Forces structured planning (routes through tech-lead for complex tasks) → CONTEXT.md → halts for approval
/ship	Code review → conventional commit → push → PR creation
/review [target]	Trigger code-reviewer on a file, diff, or PR
/adr "<title>"	Create a new Architecture Decision Record in MADR format (auto-increments)
/audit	Run tech-debt-hunter on the full codebase → saves to docs/health-report-<date>.md
/research "<question>"	Run research-analyst for evidence-based tech comparison → docs/research/<topic>.md
/release	Run release-manager pre-merge validation + generate draft release notes
/sync-vault	Sync session decisions and logs to Obsidian vault
/debug "<symptom>"	Structured root cause investigation via debugger agent
/refactor <target>	Refactor with mandatory test coverage checks via refactor agent

Example: /ship workflow

1. Pre-flight check — git diff --stat HEAD + git status
2. Automated code review — invokes the code-reviewer subagent
3. Blocker gate — halts if any 🔴 BLOCKER issues found
4. Conventional commit — feat(scope): description format
5. Push — git push origin <branch>
6. PR creation — uses .github/pull_request_template.md

Example: /plan output

## Active Plan

### Goal
Add OAuth2 PKCE flow for mobile clients.

### Affected Files
| File | Change Type | Why |
|---|---|---|
| src/auth/oauth.py | modify | Add PKCE flow handler |
| tests/test_oauth.py | create | Test PKCE exchange |

### Approach
1. Implement PKCE code verifier/challenge generation
2. Add /auth/token endpoint with code_verifier validation
3. Update auth middleware to accept PKCE tokens

### Risks
- Breaking change for existing clients using implicit flow

### Definition of Done
- [ ] All affected tests pass
- [ ] No new lint errors
- [ ] ADR created for deprecating implicit flow

---

🎓 Skills

Skills are persistent reference documents that Claude uses during specific tasks.

Skill	Purpose	Used By
commit-style	Conventional Commits spec + good/bad examples	/ship, all commits
adr-writer	MADR format with real-world examples	/adr
data-contracts	datacontract.yaml, dbt contracts, Great Expectations	data-engineer agent
sql-review	Performance checklist, anti-patterns, EXPLAIN guide	data-engineer, SQL reviews

---

🪝 Hooks

Hook	Trigger	What It Does
session-start.sh	Session start	Injects actionable CONTEXT.md sections (Now, Active Plan, Blockers, Next Up)
pre-tool-use.sh	Before Glob or Grep	Injects graphify-out/GRAPH_REPORT.md architecture context before any file search
post-edit.sh	After Edit or Write	Auto-formats: ruff (Python), prettier (TS/JS/YAML/MD), sqlfluff (SQL), gofmt (Go), shfmt (Bash)
subagent-stop.sh	Subagent completes	Logs subagent completion timestamp to CONTEXT.md for main session awareness
stop.sh	Session end	Writes CONTEXT.md snapshot to ~/vault/logs/<project>/<date>.md

All hooks use set -euo pipefail. Missing formatters are skipped silently — hooks never block your work.

---

🎯 Customization by Stack

🐍 Python / Data / ML Project

# In CLAUDE.md
Stack: Python 3.12, Databricks, dbt, MLflow, Azure

Enable data-engineer and ml-engineer as primary agents. Add dbt-specific hooks.

📖 See examples/data-ml-project/CLAUDE.md for a complete example.

⚛️ TypeScript / Web Fullstack

Stack: TypeScript, React, Next.js, Fastify, PostgreSQL

Enable frontend and backend as primary agents. Set prettier as the default formatter.

📖 See examples/web-fullstack-project/CLAUDE.md for a complete example.

🏢 SaaS Product

Stack: Python (FastAPI), TypeScript (React), PostgreSQL (multi-tenant), Redis

Add multi-tenancy rules to CLAUDE.md. Enable security-auditor as a required gate before every release. Add feature flag conventions.

📖 See examples/saas-project/CLAUDE.md for a complete example.

✂️ Removing what you don't need

If you're not using...	Remove
Obsidian	stop.sh hook + /sync-vault command
Graphify	pre-tool-use.sh hook + graphify-rebuild.yml workflow
A specific language	Formatter branches from post-edit.sh that don't apply

---

📂 Project Structure

cortex-ai/
├── .claude/
│   ├── agents/                    # 19 specialized subagents
│   │   ├── tech-lead.md           # Orchestrator — start here for complex tasks
│   │   ├── product-manager.md     # Requirements + acceptance criteria
│   │   ├── architect.md
│   │   ├── code-reviewer.md
│   │   ├── debugger.md
│   │   ├── refactor.md
│   │   ├── test-writer.md
│   │   ├── data-engineer.md
│   │   ├── ml-engineer.md
│   │   ├── frontend.md
│   │   ├── backend.md
│   │   ├── devops.md
│   │   ├── security-auditor.md
│   │   ├── performance.md
│   │   ├── docs-writer.md
│   │   ├── tech-debt-hunter.md
│   │   ├── release-manager.md
│   │   ├── research-analyst.md
│   │   └── prompt-engineer.md
│   ├── commands/                  # 11 slash commands
│   │   ├── plan.md                # Structured planning (routes through tech-lead)
│   │   ├── ship.md                # review → commit → push → PR
│   │   ├── review.md
│   │   ├── adr.md
│   │   ├── audit.md               # Tech debt report via tech-debt-hunter
│   │   ├── research.md            # Technology comparison via research-analyst
│   │   ├── release.md             # Pre-release validation via release-manager
│   │   ├── sync-vault.md
│   │   ├── debug.md
│   │   ├── refactor.md
│   │   └── setup.md
│   ├── hooks/                     # 5 automation hooks
│   │   ├── session-start.sh       # Inject CONTEXT.md at session start
│   │   ├── pre-tool-use.sh        # Graphify context before searches
│   │   ├── post-edit.sh           # Auto-format on edit
│   │   ├── subagent-stop.sh       # Log subagent completion
│   │   └── stop.sh                # Vault session log on exit
│   ├── rules/                     # Path-specific coding standards
│   │   ├── python.md              # globs: **/*.py
│   │   ├── typescript.md          # globs: **/*.ts, **/*.tsx
│   │   ├── sql.md                 # globs: **/*.sql
│   │   ├── code-style.md
│   │   ├── git-workflow.md
│   │   ├── security.md
│   │   └── testing.md
│   ├── skills/                    # Reusable reference documents
│   │   ├── commit-style/SKILL.md
│   │   ├── adr-writer/SKILL.md
│   │   ├── data-contracts/SKILL.md
│   │   └── sql-review/SKILL.md
│   └── settings.json              # Hooks + permissions allowlist + model config
├── docs/
│   ├── adr/
│   │   ├── 0000-template.md       # MADR template
│   │   └── 0001-use-this-template.md
│   ├── architecture.md            # Four-layer architecture + agent org chart
│   ├── runbook.md                 # Setup, config, troubleshooting
│   └── obsidian-vault-setup.md    # Second Brain configuration
├── examples/
│   ├── data-ml-project/CLAUDE.md  # Python · Databricks · dbt · MLflow
│   ├── web-fullstack-project/CLAUDE.md  # TypeScript · React · Next.js
│   └── saas-project/CLAUDE.md     # Multi-tenant SaaS · FastAPI · Redis
├── scripts/
│   ├── setup.sh                   # Bootstrap for Unix/macOS/WSL
│   └── setup.ps1                  # Bootstrap for Windows (native PowerShell)
├── .github/
│   ├── workflows/
│   │   ├── ci.yml                 # Lint + test + pre-commit + template validation
│   │   └── graphify-rebuild.yml   # Auto-rebuild knowledge graph on push
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.md
│   │   └── feature_request.md
│   └── pull_request_template.md
├── .vscode/
│   ├── settings.json              # Format-on-save, ruff/prettier per language
│   └── extensions.json            # Recommended extensions
├── CLAUDE.md                      # Project identity — configure this first
├── CONTEXT.md                     # Live session state
├── CONTRIBUTING.md
├── CHANGELOG.md
├── SECURITY.md
├── LICENSE
├── Justfile                       # Task runner: init/format/lint/test/graph/health
├── .pre-commit-config.yaml        # ruff · prettier · sqlfluff · gitleaks · commitlint
├── commitlint.config.js           # Conventional Commits enforcement
├── .markdownlint.json             # Markdown consistency rules
├── .sqlfluff                      # SQL formatting config
├── .editorconfig
├── .gitattributes
└── .gitignore

---

🤝 How Agents Collaborate

The real power is in how agents work together. tech-lead orchestrates; specialists execute.

Example: Building a new feature end-to-end

User: /plan "add multi-tenant support to the orders API"

tech-lead → classifies: Feature/L — 3 domains
  ├── product-manager   → acceptance criteria + edge cases (parallel)
  └── architect         → database isolation strategy + ADR (parallel)

  [both complete]
  ├── backend           → implement tenant middleware
  ├── security-auditor  → review isolation logic
  └── test-writer       → cross-tenant integration tests

code-reviewer → /review before merge
release-manager → /release pre-merge validation

Example: Quarterly maintenance cycle

User: /audit

tech-debt-hunter → full codebase scan
  → docs/health-report-2026-Q1.md (Critical: 2, High: 5, Watchlist: 8)

User selects top 3 items:

refactor → surgical fix (one per commit, tests first)
architect → ADR for structural change touching 5+ files
test-writer → characterization tests before each refactor

Example: Technology decision

User: /research "Celery vs Temporal for workflow orchestration"

research-analyst → evaluates 3 candidates (Celery, Temporal, Prefect)
  → docs/research/workflow-orchestration.md
  → weighted scorecard, evidence-based recommendation, fallback option

User: /adr "adopt Temporal for workflow orchestration"
  → docs/adr/0005-temporal-for-workflows.md

---

🔀 Worktrees Workflow

Parallelize independent features using git worktrees with Claude Code:

# Start a new feature in an isolated worktree
git worktree add ../my-project-feature-auth feat/auth-refactor
cd ../my-project-feature-auth
claude .

# Work on main feature in parallel
cd ../my-project
claude .

# Clean up when merged
git worktree remove ../my-project-feature-auth

Each Claude Code session in a worktree has its own context, preventing state contamination between parallel workstreams.

---

❓ FAQ

Do I need Graphify to use this template?

No. Graphify is completely optional. Without it, the pre-tool-use.sh hook silently does nothing (it checks for the file first). Remove the hook and the graphify-rebuild.yml workflow if you don't use it.

Do I need Obsidian?

No. Obsidian is the recommended Second Brain layer, but the template works without it. Remove the stop.sh hook and the /sync-vault command if you don't use Obsidian.

Does this work on Windows?

Yes — two paths:

Option A: Native Windows (PowerShell)

.\scripts\setup.ps1   # installs pre-commit, ruff, prettier, graphify

Hooks require Git Bash on PATH (comes with Git for Windows). Claude Code on Windows uses Git Bash for hook execution.

Option B: WSL (recommended for full compatibility)

bash scripts/setup.sh

WSL gives you a full Linux environment. All hooks, formatters, and the Justfile work without any adaptation.

How much do subagents cost in tokens?

Each subagent invocation is a separate Claude session with its own context window. Costs depend on your Claude Code plan and the model you use. The template does not hardcode a model — you can use any Claude model supported by Claude Code.

Can I use this with an existing project?

Yes. Copy the .claude/, docs/, CLAUDE.md, CONTEXT.md, .editorconfig, and .gitattributes into your existing repo. Merge the .gitignore entries. Configure CLAUDE.md with your project details.

Hooks aren't firing — what do I check?

1. Verify hooks are registered in .claude/settings.json
2. Make scripts executable: chmod +x .claude/hooks/*.sh
3. Verify formatters are on PATH: which ruff / which prettier

📖 Full troubleshooting: docs/runbook.md

How does sandboxing work? Can hooks or agents harm my system?

Claude Code runs hooks and Bash tool calls in your local environment — there is no sandbox by default. This means hooks have full access to your filesystem and network. The template is designed with this in mind:

What the template does to limit blast radius:

• settings.json uses an explicit allowlist (permissions.allow) — only the commands listed can run without a prompt. Everything else triggers a user confirmation.
• Hooks use set -euo pipefail — they fail fast and loudly instead of silently continuing after an error.
• post-edit.sh only invokes formatters that are already on your PATH and skips missing ones silently — it never installs anything.
• stop.sh and session-start.sh are read-only relative to your codebase — they only write to ~/vault/.
• Subagents (agents in .claude/agents/) are restricted to the tools: list in their frontmatter. Agents without Bash cannot run shell commands.

What you should verify before using:

• Review .claude/settings.json — confirm the allow list matches tools you actually use.
• Run bash -n .claude/hooks/*.sh to syntax-check all hooks before they fire.
• If working with sensitive codebases, use Claude Code's built-in sandboxing mode (claude --sandbox) which restricts filesystem access to the project directory.

CLAUDE.local.md and .claude/settings.local.json are gitignored — use them for machine-local overrides (personal vault paths, API keys for local tools) without exposing them to the repo.

---

💰 Token Cost & FinOps

For teams tracking AI spend, here's how Cortex AI maps to token consumption:

Action	Token Impact	Notes
Session start (CLAUDE.md + CONTEXT.md)	~2-4K tokens input	Fixed cost, read once per session
Subagent invocation	~3-8K tokens per call	Each agent has its own context window
/plan	~5-10K tokens	Reads files + produces structured plan
/ship	~8-15K tokens	Runs code review + commit + PR
/review on a large diff	~10-20K tokens	Scales with diff size
Graphify context injection	~1-3K tokens	Per search, only if graph exists

Cost optimization tips:

• 🎯 Use the right agent — specialized agents produce better output in fewer iterations than the general session
• 📏 Use /plan first — structured planning reduces back-and-forth, which is the #1 token cost driver
• 🔍 Keep CONTEXT.md lean — remove stale plans and resolved blockers to reduce input tokens
• ⚙️ Choose your model wisely — the template is model-agnostic; Haiku is 60x cheaper than Opus for routine tasks
• 📉 Monitor via Claude Code settings — check your usage dashboard at console.anthropic.com

💡 Rule of thumb: a typical feature cycle (/plan → implement → /ship) costs roughly 20-40K tokens. At Sonnet pricing, that's about $0.10-0.25 per feature shipped.

---

🗺️ Roadmap

Shipped in v0.3.0:

• ✅ 7 new agents: tech-lead, product-manager, tech-debt-hunter, devops, prompt-engineer, release-manager, research-analyst
• ✅ 3 new commands: /audit, /research, /release
• ✅ Pre-commit enforcement (ruff, prettier, sqlfluff, gitleaks, commitlint, markdownlint)
• ✅ Justfile task runner (just init, just format, just lint, just health)
• ✅ Bootstrap scripts for Unix and Windows
• ✅ VSCode workspace settings + extension recommendations
• ✅ Path-specific rules (.claude/rules/)
• ✅ 5 hooks (added session-start, subagent-stop)
• ✅ model: frontmatter on all agents

Planned:

• 🗄️ Database migration agent (Alembic, Flyway, Drizzle)
• 📋 /standup command — daily summary from CONTEXT.md + git log
• 📏 /estimate command — complexity and effort estimation
• 🤝 GitHub Copilot coexistence guide
• 🐹 Example CLAUDE.md for Go projects
• ☁️ Example CLAUDE.md for infrastructure/IaC projects

---

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for standards, process, and commit conventions.

This template is opinionated by design — that is its value. See what makes a good contribution vs. what will be declined.

Open a discussion before implementing non-trivial changes.

---

📄 License

MIT License — see LICENSE

---

👀 See It In Action

Real /ship output — what Claude actually produces

## Review Summary
**Verdict:** APPROVE
**Blockers:** 0  **Shoulds:** 2  **Nits:** 1

Clean implementation of the PKCE flow. The token exchange logic is correct
and the code_verifier validation matches RFC 7636. Two suggestions below.

---

### src/auth/oauth.py:42-48
🟡 SHOULD

**Issue:** code_verifier is generated with `random.choices()` instead of `secrets`
**Why it matters:** `random` is not cryptographically secure — predictable verifiers
nullify the PKCE security benefit.
**Suggestion:** Use `secrets.token_urlsafe(32)` instead.

---

### src/auth/oauth.py:67
🟡 SHOULD

**Issue:** Missing rate limit on the token exchange endpoint
**Why it matters:** Without rate limiting, an attacker can brute-force authorization codes.
**Suggestion:** Apply the existing `@rate_limit(10, per=60)` decorator.

---

Commit: feat(auth): add OAuth2 PKCE flow for mobile clients
PR: #142 → main

Real /plan output — structured thinking before code

## Active Plan

### Goal
Replace the implicit OAuth flow with PKCE for mobile clients (RFC 7636 compliance).

### Affected Files
| File | Change Type | Why |
|---|---|---|
| src/auth/oauth.py | modify | Add PKCE code_verifier/challenge logic |
| src/auth/middleware.py | modify | Accept PKCE-issued tokens |
| tests/test_oauth.py | create | Test PKCE exchange + edge cases |
| docs/adr/0004-pkce.md | create | Document deprecation of implicit flow |

### Approach
1. Generate code_verifier (43-128 chars, unreserved chars) and code_challenge (S256)
2. Add /auth/authorize endpoint accepting code_challenge + method
3. Add /auth/token endpoint validating code_verifier against stored challenge
4. Update middleware to validate PKCE-issued JWTs
5. Deprecate implicit flow with 90-day sunset notice

### Risks
- Breaking change for existing mobile clients using implicit flow
- Mitigation: Feature flag + parallel support for 90 days

### Definition of Done
- [ ] All tests pass (unit + integration)
- [ ] No new lint errors
- [ ] ADR-0004 created for implicit flow deprecation
- [ ] CHANGELOG.md updated

---

Built by Gabriel Henrique
Stack focus: Python · SQL · Databricks · Azure · TypeScript · React

 

---

_{Acknowledgments: Anthropic (Claude Code) · Obsidian (Second Brain) · MADR (ADR format) · Conventional Commits}

_{"The best AI coding assistant is the one that knows your codebase as well as you do."
Cortex AI — Engineered context, not re-explained context.}