@leing2021/super-pi 0.17.0 → 0.18.1

package/README.md

@@ -85,7 +85,7 @@ Next time `02-plan` or `04-review` runs, a grep-first search strategy automatica
 
 ## Technical Architecture
 
-### 9 Skills (workflow nodes)
+### 10 Skills (workflow nodes)
 
 | Skill | One-liner | Core Tool |
 |-------|-----------|-----------|
@@ -98,6 +98,7 @@ Next time `02-plan` or `04-review` runs, a grep-first search strategy automatica
 | `07-worktree` | Git worktree isolated development | `worktree_manager` |
 | `08-status` | Scan artifacts, report progress | `workflow_state`, `session_history` |
 | `09-help` | Usage guide | — |
+| `10-rules` | Progressive rule loading for coding standards | — |
 
 ### 15 Tools (underlying capabilities)
 
@@ -121,9 +122,33 @@ Next time `02-plan` or `04-review` runs, a grep-first search strategy automatica
 
 ---
 
+## Token Cost
+
+New conversation overhead: **~2,500 tokens** (1.26% of Claude Sonnet 4's 200K context).
+
+| Component | Tokens | When loaded |
+|-----------|--------|-------------|
+| 10 skill registrations | ~615 | Every conversation (fixed) |
+| 13 tool registrations | ~1,914 | Every conversation (fixed) |
+| Hooks & filters | 0 | Runtime interception, zero prompt cost |
+| Single skill trigger | ~1,000–4,000 | On-demand via `read` |
+| Rules minimal (2 files) | ~900 | Before plan/work |
+| Rules + language (7 files) | ~2,600 | Before work with specific language |
+
+| vs bare Pi | vs global rules injection | vs super-pi |
+|-----------|----------------------|------------|
+| No rules | All rules loaded upfront | Progressive on-demand |
+| No output filtering | No output filtering | Auto-compress (bash ~65–98%, read ~30–60%) |
+| No TDD gate | No TDD gate | Hard gate prevents rework |
+| 0 tokens | ~5,000–36,000 tokens | **~2,500 tokens** |
+
+Single `npm install` output filtered once pays for the entire overhead. Full evaluation → [`docs/token-cost-evaluation.md`](docs/token-cost-evaluation.md)
+
+---
+
 ## Code Scale
 
-~2500 lines of TypeScript implementing 15 tools, 22 Markdown reference files driving 9 skills' behavioral strategies, 162 tests covering all tool logic.
+~2500 lines of TypeScript implementing 15 tools, 22 Markdown reference files + 78 rule files driving 10 skills, 162 tests covering all tool logic.
 
 Not a heavy framework. Each tool has a single responsibility, each skill works independently, and together they form a complete workflow.
 
@@ -204,22 +229,110 @@ your-project/
 
 **Recommendation: commit everything to git** — these files are the project's traceable memory.
 
+### `10-rules`: Progressive Rule Loading
+
+Built-in coding rules live under `rules/` in the package. The `10-rules` skill loads them **progressively** — never all at once, only what the current task needs.
+
+**How it works:**
+
+```
+system prompt (30 tokens: skill name + description)
+  → 10-rules SKILL.md (~200 tokens: loading decision tree)
+    → specific rule files via read tool (on-demand, 900–2600 tokens)
+```
+
+Three CE skills auto-trigger rule loading at their entry points:
+
+| Skill | Rules pre-loaded |
+|-------|-----------------|
+| `02-plan` | `common/development-workflow.md` + `common/testing.md` |
+| `03-work` | Language-specific rules matching the active codebase |
+| `04-review` | `common/code-review.md` + language rules for changed files |
+
+**Rule precedence** (when layers overlap on the same topic):
+
+```
+language-specific  >  web  >  common
+```
+
+No rules are loaded when you brainstorm, check status, or do non-code tasks. Zero waste.
+
+#### Included rule layers
+
+| Layer | Files | When loaded |
+|-------|-------|------------|
+| `common/` | 10 files | Always (baseline for all tasks) |
+| `typescript/`, `python/`, `cpp/`, `csharp/`, `dart/`, `golang/`, `java/`, `kotlin/`, `perl/`, `php/`, `rust/`, `swift/` | 5 files each | When the task touches that language |
+| `web/` | 7 files (includes `design-quality.md`, `performance.md`) | When frontend/browser is relevant |
+
+#### Customizing rules for your project
+
+Two rule sources exist, with project-level taking priority:
+
+| Source | Location | Survives `pi update`? |
+|--------|----------|----------------------|
+| **Project-level** | `{your-project-root}/rules/` | ✅ Yes |
+| Package-level | Inside `node_modules/@leing2021/super-pi/rules/` | ❌ No |
+
+To customize, create a `rules/` directory in your project root. `10-rules` checks it first — if a file exists there, it overrides the package default for that topic.
+
+**Add a language** — create a new directory with the 5 standard topics:
+
+```bash
+mkdir rules/elixir
+touch rules/elixir/{coding-style,testing,patterns,security,hooks}.md
+```
+
+Each file should start with:
+
+```markdown
+> This file extends [common/xxx.md](../common/xxx.md) with Elixir-specific content.
+```
+
+**Remove unused languages** — just delete the directory:
+
+```bash
+rm -rf rules/perl rules/cpp  # don't need these? remove them
+```
+
+**Tweak a rule** — edit the `.md` file directly:
+
+```bash
+# Override testing conventions for your team
+vim rules/common/testing.md
+
+# Override for a specific language
+vim rules/typescript/testing.md
+```
+
+**Add a new topic** — create a new `.md` in the appropriate layer:
+
+```bash
+# Common topic
+vim rules/common/api-design.md
+
+# Language-specific override
+vim rules/python/api-design.md
+```
+
+The `10-rules` skill will pick up any `.md` file in `rules/` — no configuration needed. If a language directory exists, it's available for loading. If it's gone, it's simply never loaded.
+
 ---
 
-## Design Philosophy
+## Design Philosophy & Acknowledgements
 
 **80% planning and review, 20% execution.**
 
 The goal isn't making AI write code faster — it's making AI think before writing, review after writing, and compound learnings after reviewing. Speed comes from fewer rewrites, not from skipping steps.
 
-**The best ideas from four projects, reimplemented natively for Pi:**
+The following projects directly inspired this work:
 
-- **Compound Engineering** (Every Inc.) → The five-step loop + knowledge compounding backbone
-- **Superpowers** (Jesse Vincent) → Strict TDD gates + design checklists + review discipline
-- **Everything Claude Code** (140K+ stars) → Parallel subagent orchestration + checkpoint resume + continuous learning
-- **gstack** (Garry Tan / YC) → YC-style forcing questions + CEO Review cognitive frameworks + browser QA
+- **[everything-claude-code](https://github.com/affaan-m/everything-claude-code)** (162K★) → Parallel subagent orchestration, checkpoint resume, continuous learning
+- **[superpowers](https://github.com/obra/superpowers)** (161K★) → Strict TDD gates, design checklists, review discipline
+- **[gstack](https://github.com/garrytan/gstack)** (78K★) → YC-style forcing questions, CEO Review frameworks, browser QA
+- **[compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin)** (14K★) → Five-step loop, knowledge compounding backbone
 
-Not a fork. Not a wrapper. The methodologies are extracted and rebuilt with Pi's native tool + skill system.
+Not a fork. Not a wrapper. Methodologies extracted and rebuilt with Pi's native tool + skill system.
 
 ---
 
@@ -238,6 +351,13 @@ Not a fork. Not a wrapper. The methodologies are extracted and rebuilt with Pi's
 
 ## Changelog
 
+### 0.18.0 — Progressive rules
+- Built-in `rules/` directory with 13 language layers + common + web (78 Markdown files)
+- New `10-rules` skill: progressive on-demand loading, zero waste
+- `02-plan`, `03-work`, `04-review` auto-trigger rule loading at entry points
+- Users can add/remove languages and edit rules freely — plain Markdown, no config
+- 10 skills, 15 tools, 162 tests passing
+
 ### 0.17.0 — Subagent safety
 - Recursion depth guard (`PI_SUBAGENT_DEPTH` / `PI_SUBAGENT_MAX_DEPTH`) prevents runaway nesting
 - Async mutex for `process.env` concurrency safety during parallel subagent execution

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leing2021/super-pi",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "private": false,
   "type": "module",
   "description": "Pi-native Compound Engineering package for iterative development workflows",
@@ -24,6 +24,7 @@
   "files": [
     "skills",
     "extensions",
+    "rules",
     "README.md",
     "package.json"
   ],

package/rules/README.md

@@ -0,0 +1,111 @@
+# Rules
+## Structure
+
+Rules are organized into a **common** layer plus **language-specific** directories:
+
+```
+rules/
+├── common/          # Language-agnostic principles (always install)
+│   ├── coding-style.md
+│   ├── git-workflow.md
+│   ├── testing.md
+│   ├── performance.md
+│   ├── patterns.md
+│   ├── hooks.md
+│   ├── agents.md
+│   └── security.md
+├── typescript/      # TypeScript/JavaScript specific
+├── python/          # Python specific
+├── golang/          # Go specific
+├── web/             # Web and frontend specific
+├── swift/           # Swift specific
+└── php/             # PHP specific
+```
+
+- **common/** contains universal principles — no language-specific code examples.
+- **Language directories** extend the common rules with framework-specific patterns, tools, and code examples. Each file references its common counterpart.
+
+## Installation
+
+### Option 1: Install Script (Recommended)
+
+```bash
+# Install common + one or more language-specific rule sets
+./install.sh typescript
+./install.sh python
+./install.sh golang
+./install.sh web
+./install.sh swift
+./install.sh php
+
+# Install multiple languages at once
+./install.sh typescript python
+```
+
+### Option 2: Manual Installation
+
+> **Important:** Copy entire directories — do NOT flatten with `/*`.
+> Common and language-specific directories contain files with the same names.
+> Flattening them into one directory causes language-specific files to overwrite
+> common rules, and breaks the relative `../common/` references used by
+> language-specific files.
+
+```bash
+# Install common rules (required for all projects)
+cp -r rules/common ~/.claude/rules/common
+
+# Install language-specific rules based on your project's tech stack
+cp -r rules/typescript ~/.claude/rules/typescript
+cp -r rules/python ~/.claude/rules/python
+cp -r rules/golang ~/.claude/rules/golang
+cp -r rules/web ~/.claude/rules/web
+cp -r rules/swift ~/.claude/rules/swift
+cp -r rules/php ~/.claude/rules/php
+
+# Attention ! ! ! Configure according to your actual project requirements; the configuration here is for reference only.
+```
+
+## Rules vs Skills
+
+- **Rules** define standards, conventions, and checklists that apply broadly (e.g., "80% test coverage", "no hardcoded secrets").
+- **Skills** (`skills/` directory) provide deep, actionable reference material for specific tasks (e.g., `python-patterns`, `golang-testing`).
+
+Language-specific rule files reference relevant skills where appropriate. Rules tell you *what* to do; skills tell you *how* to do it.
+
+## Adding a New Language
+
+To add support for a new language (e.g., `rust/`):
+
+1. Create a `rules/rust/` directory
+2. Add files that extend the common rules:
+   - `coding-style.md` — formatting tools, idioms, error handling patterns
+   - `testing.md` — test framework, coverage tools, test organization
+   - `patterns.md` — language-specific design patterns
+   - `hooks.md` — PostToolUse hooks for formatters, linters, type checkers
+   - `security.md` — secret management, security scanning tools
+3. Each file should start with:
+   ```
+   > This file extends [common/xxx.md](../common/xxx.md) with <Language> specific content.
+   ```
+4. Reference existing skills if available, or create new ones under `skills/`.
+
+For non-language domains like `web/`, follow the same layered pattern when there is enough reusable domain-specific guidance to justify a standalone ruleset.
+
+## Rule Priority
+
+When language-specific rules and common rules conflict, **language-specific rules take precedence** (specific overrides general). This follows the standard layered configuration pattern (similar to CSS specificity or `.gitignore` precedence).
+
+- `rules/common/` defines universal defaults applicable to all projects.
+- `rules/golang/`, `rules/python/`, `rules/swift/`, `rules/php/`, `rules/typescript/`, etc. override those defaults where language idioms differ.
+
+### Example
+
+`common/coding-style.md` recommends immutability as a default principle. A language-specific `golang/coding-style.md` can override this:
+
+> Idiomatic Go uses pointer receivers for struct mutation — see [common/coding-style.md](../common/coding-style.md) for the general principle, but Go-idiomatic mutation is preferred here.
+
+### Common rules with override notes
+
+Rules in `rules/common/` that may be overridden by language-specific files are marked with:
+
+> **Language note**: This rule may be overridden by language-specific rules for languages where this pattern is not idiomatic.

package/rules/common/agents.md

@@ -0,0 +1,50 @@
+# Agent Orchestration
+
+## Available Agents
+
+Located in `~/.claude/agents/`:
+
+| Agent | Purpose | When to Use |
+|-------|---------|-------------|
+| planner | Implementation planning | Complex features, refactoring |
+| architect | System design | Architectural decisions |
+| tdd-guide | Test-driven development | New features, bug fixes |
+| code-reviewer | Code review | After writing code |
+| security-reviewer | Security analysis | Before commits |
+| build-error-resolver | Fix build errors | When build fails |
+| e2e-runner | E2E testing | Critical user flows |
+| refactor-cleaner | Dead code cleanup | Code maintenance |
+| doc-updater | Documentation | Updating docs |
+| rust-reviewer | Rust code review | Rust projects |
+
+## Immediate Agent Usage
+
+No user prompt needed:
+1. Complex feature requests - Use **planner** agent
+2. Code just written/modified - Use **code-reviewer** agent
+3. Bug fix or new feature - Use **tdd-guide** agent
+4. Architectural decision - Use **architect** agent
+
+## Parallel Task Execution
+
+ALWAYS use parallel Task execution for independent operations:
+
+```markdown
+# GOOD: Parallel execution
+Launch 3 agents in parallel:
+1. Agent 1: Security analysis of auth module
+2. Agent 2: Performance review of cache system
+3. Agent 3: Type checking of utilities
+
+# BAD: Sequential when unnecessary
+First agent 1, then agent 2, then agent 3
+```
+
+## Multi-Perspective Analysis
+
+For complex problems, use split role sub-agents:
+- Factual reviewer
+- Senior engineer
+- Security expert
+- Consistency reviewer
+- Redundancy checker

package/rules/common/code-review.md

@@ -0,0 +1,124 @@
+# Code Review Standards
+
+## Purpose
+
+Code review ensures quality, security, and maintainability before code is merged. This rule defines when and how to conduct code reviews.
+
+## When to Review
+
+**MANDATORY review triggers:**
+
+- After writing or modifying code
+- Before any commit to shared branches
+- When security-sensitive code is changed (auth, payments, user data)
+- When architectural changes are made
+- Before merging pull requests
+
+**Pre-Review Requirements:**
+
+Before requesting review, ensure:
+
+- All automated checks (CI/CD) are passing
+- Merge conflicts are resolved
+- Branch is up to date with target branch
+
+## Review Checklist
+
+Before marking code complete:
+
+- [ ] Code is readable and well-named
+- [ ] Functions are focused (<50 lines)
+- [ ] Files are cohesive (<800 lines)
+- [ ] No deep nesting (>4 levels)
+- [ ] Errors are handled explicitly
+- [ ] No hardcoded secrets or credentials
+- [ ] No console.log or debug statements
+- [ ] Tests exist for new functionality
+- [ ] Test coverage meets 80% minimum
+
+## Security Review Triggers
+
+**STOP and use security-reviewer agent when:**
+
+- Authentication or authorization code
+- User input handling
+- Database queries
+- File system operations
+- External API calls
+- Cryptographic operations
+- Payment or financial code
+
+## Review Severity Levels
+
+| Level | Meaning | Action |
+|-------|---------|--------|
+| CRITICAL | Security vulnerability or data loss risk | **BLOCK** - Must fix before merge |
+| HIGH | Bug or significant quality issue | **WARN** - Should fix before merge |
+| MEDIUM | Maintainability concern | **INFO** - Consider fixing |
+| LOW | Style or minor suggestion | **NOTE** - Optional |
+
+## Agent Usage
+
+Use these agents for code review:
+
+| Agent | Purpose |
+|-------|---------|
+| **code-reviewer** | General code quality, patterns, best practices |
+| **security-reviewer** | Security vulnerabilities, OWASP Top 10 |
+| **typescript-reviewer** | TypeScript/JavaScript specific issues |
+| **python-reviewer** | Python specific issues |
+| **go-reviewer** | Go specific issues |
+| **rust-reviewer** | Rust specific issues |
+
+## Review Workflow
+
+```
+1. Run git diff to understand changes
+2. Check security checklist first
+3. Review code quality checklist
+4. Run relevant tests
+5. Verify coverage >= 80%
+6. Use appropriate agent for detailed review
+```
+
+## Common Issues to Catch
+
+### Security
+
+- Hardcoded credentials (API keys, passwords, tokens)
+- SQL injection (string concatenation in queries)
+- XSS vulnerabilities (unescaped user input)
+- Path traversal (unsanitized file paths)
+- CSRF protection missing
+- Authentication bypasses
+
+### Code Quality
+
+- Large functions (>50 lines) - split into smaller
+- Large files (>800 lines) - extract modules
+- Deep nesting (>4 levels) - use early returns
+- Missing error handling - handle explicitly
+- Mutation patterns - prefer immutable operations
+- Missing tests - add test coverage
+
+### Performance
+
+- N+1 queries - use JOINs or batching
+- Missing pagination - add LIMIT to queries
+- Unbounded queries - add constraints
+- Missing caching - cache expensive operations
+
+## Approval Criteria
+
+- **Approve**: No CRITICAL or HIGH issues
+- **Warning**: Only HIGH issues (merge with caution)
+- **Block**: CRITICAL issues found
+
+## Integration with Other Rules
+
+This rule works with:
+
+- [testing.md](testing.md) - Test coverage requirements
+- [security.md](security.md) - Security checklist
+- [git-workflow.md](git-workflow.md) - Commit standards
+- [agents.md](agents.md) - Agent delegation

package/rules/common/coding-style.md

@@ -0,0 +1,90 @@
+# Coding Style
+
+## Immutability (CRITICAL)
+
+ALWAYS create new objects, NEVER mutate existing ones:
+
+```
+// Pseudocode
+WRONG:  modify(original, field, value) → changes original in-place
+CORRECT: update(original, field, value) → returns new copy with change
+```
+
+Rationale: Immutable data prevents hidden side effects, makes debugging easier, and enables safe concurrency.
+
+## Core Principles
+
+### KISS (Keep It Simple)
+
+- Prefer the simplest solution that actually works
+- Avoid premature optimization
+- Optimize for clarity over cleverness
+
+### DRY (Don't Repeat Yourself)
+
+- Extract repeated logic into shared functions or utilities
+- Avoid copy-paste implementation drift
+- Introduce abstractions when repetition is real, not speculative
+
+### YAGNI (You Aren't Gonna Need It)
+
+- Do not build features or abstractions before they are needed
+- Avoid speculative generality
+- Start simple, then refactor when the pressure is real
+
+## File Organization
+
+MANY SMALL FILES > FEW LARGE FILES:
+- High cohesion, low coupling
+- 200-400 lines typical, 800 max
+- Extract utilities from large modules
+- Organize by feature/domain, not by type
+
+## Error Handling
+
+ALWAYS handle errors comprehensively:
+- Handle errors explicitly at every level
+- Provide user-friendly error messages in UI-facing code
+- Log detailed error context on the server side
+- Never silently swallow errors
+
+## Input Validation
+
+ALWAYS validate at system boundaries:
+- Validate all user input before processing
+- Use schema-based validation where available
+- Fail fast with clear error messages
+- Never trust external data (API responses, user input, file content)
+
+## Naming Conventions
+
+- Variables and functions: `camelCase` with descriptive names
+- Booleans: prefer `is`, `has`, `should`, or `can` prefixes
+- Interfaces, types, and components: `PascalCase`
+- Constants: `UPPER_SNAKE_CASE`
+- Custom hooks: `camelCase` with a `use` prefix
+
+## Code Smells to Avoid
+
+### Deep Nesting
+
+Prefer early returns over nested conditionals once the logic starts stacking.
+
+### Magic Numbers
+
+Use named constants for meaningful thresholds, delays, and limits.
+
+### Long Functions
+
+Split large functions into focused pieces with clear responsibilities.
+
+## Code Quality Checklist
+
+Before marking work complete:
+- [ ] Code is readable and well-named
+- [ ] Functions are small (<50 lines)
+- [ ] Files are focused (<800 lines)
+- [ ] No deep nesting (>4 levels)
+- [ ] Proper error handling
+- [ ] No hardcoded values (use constants or config)
+- [ ] No mutation (immutable patterns used)

package/rules/common/development-workflow.md

@@ -0,0 +1,44 @@
+# Development Workflow
+
+> This file extends [common/git-workflow.md](./git-workflow.md) with the full feature development process that happens before git operations.
+
+The Feature Implementation Workflow describes the development pipeline: research, planning, TDD, code review, and then committing to git.
+
+## Feature Implementation Workflow
+
+0. **Research & Reuse** _(mandatory before any new implementation)_
+   - **GitHub code search first:** Run `gh search repos` and `gh search code` to find existing implementations, templates, and patterns before writing anything new.
+   - **Library docs second:** Use Context7 or primary vendor docs to confirm API behavior, package usage, and version-specific details before implementing.
+   - **Exa only when the first two are insufficient:** Use Exa for broader web research or discovery after GitHub search and primary docs.
+   - **Check package registries:** Search npm, PyPI, crates.io, and other registries before writing utility code. Prefer battle-tested libraries over hand-rolled solutions.
+   - **Search for adaptable implementations:** Look for open-source projects that solve 80%+ of the problem and can be forked, ported, or wrapped.
+   - Prefer adopting or porting a proven approach over writing net-new code when it meets the requirement.
+
+1. **Plan First**
+   - Use **planner** agent to create implementation plan
+   - Generate planning docs before coding: PRD, architecture, system_design, tech_doc, task_list
+   - Identify dependencies and risks
+   - Break down into phases
+
+2. **TDD Approach**
+   - Use **tdd-guide** agent
+   - Write tests first (RED)
+   - Implement to pass tests (GREEN)
+   - Refactor (IMPROVE)
+   - Verify 80%+ coverage
+
+3. **Code Review**
+   - Use **code-reviewer** agent immediately after writing code
+   - Address CRITICAL and HIGH issues
+   - Fix MEDIUM issues when possible
+
+4. **Commit & Push**
+   - Detailed commit messages
+   - Follow conventional commits format
+   - See [git-workflow.md](./git-workflow.md) for commit message format and PR process
+
+5. **Pre-Review Checks**
+   - Verify all automated checks (CI/CD) are passing
+   - Resolve any merge conflicts
+   - Ensure branch is up to date with target branch
+   - Only request review after these checks pass

package/rules/common/git-workflow.md

@@ -0,0 +1,24 @@
+# Git Workflow
+
+## Commit Message Format
+```
+<type>: <description>
+
+<optional body>
+```
+
+Types: feat, fix, refactor, docs, test, chore, perf, ci
+
+Note: Attribution disabled globally via ~/.claude/settings.json.
+
+## Pull Request Workflow
+
+When creating PRs:
+1. Analyze full commit history (not just latest commit)
+2. Use `git diff [base-branch]...HEAD` to see all changes
+3. Draft comprehensive PR summary
+4. Include test plan with TODOs
+5. Push with `-u` flag if new branch
+
+> For the full development process (planning, TDD, code review) before git operations,
+> see [development-workflow.md](./development-workflow.md).

package/rules/common/hooks.md

@@ -0,0 +1,30 @@
+# Hooks System
+
+## Hook Types
+
+- **PreToolUse**: Before tool execution (validation, parameter modification)
+- **PostToolUse**: After tool execution (auto-format, checks)
+- **Stop**: When session ends (final verification)
+
+## Auto-Accept Permissions
+
+Use with caution:
+- Enable for trusted, well-defined plans
+- Disable for exploratory work
+- Never use dangerously-skip-permissions flag
+- Configure `allowedTools` in `~/.claude.json` instead
+
+## TodoWrite Best Practices
+
+Use TodoWrite tool to:
+- Track progress on multi-step tasks
+- Verify understanding of instructions
+- Enable real-time steering
+- Show granular implementation steps
+
+Todo list reveals:
+- Out of order steps
+- Missing items
+- Extra unnecessary items
+- Wrong granularity
+- Misinterpreted requirements