Variet/guitar_score
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

wip: [01-stabilize] paused at task 1/1 - OCR Hallucination Immune logic via Semantic delta window and fret-isolation

Browse Source
This commit is contained in:
authentik Default Admin
2026-03-29 22:08:40 +09:00
parent aca7bf592a
commit 2507de45d3
4289 changed files with 732689 additions and 28672 deletions
Download Patch File Download Diff File Expand all files Collapse all files

164
.agent/knowledge/everything_claude/commands/aside.md Normal file
View File

@@ -0,0 +1,164 @@
---
description: Answer a quick side question without interrupting or losing context from the current task. Resume work automatically after answering.
---
# Aside Command
Ask a question mid-task and get an immediate, focused answer — then continue right where you left off. The current task, files, and context are never modified.
## When to Use
- You're curious about something while Claude is working and don't want to lose momentum
- You need a quick explanation of code Claude is currently editing
- You want a second opinion or clarification on a decision without derailing the task
- You need to understand an error, concept, or pattern before Claude proceeds
- You want to ask something unrelated to the current task without starting a new session
## Usage
```
/aside <your question>
/aside what does this function actually return?
/aside is this pattern thread-safe?
/aside why are we using X instead of Y here?
/aside what's the difference between foo() and bar()?
/aside should we be worried about the N+1 query we just added?
```
## Process
### Step 1: Freeze the current task state
Before answering anything, mentally note:
- What is the active task? (what file, feature, or problem was being worked on)
- What step was in progress at the moment `/aside` was invoked?
- What was about to happen next?
Do NOT touch, edit, create, or delete any files during the aside.
### Step 2: Answer the question directly
Answer the question in the most concise form that is still complete and useful.
- Lead with the answer, not the reasoning
- Keep it short — if a full explanation is needed, offer to go deeper after the task
- If the question is about the current file or code being worked on, reference it precisely (file path and line number if relevant)
- If answering requires reading a file, read it — but read only, never write
Format the response as:
```
ASIDE: [restate the question briefly]
[Your answer here]
— Back to task: [one-line description of what was being done]
```
### Step 3: Resume the main task
After delivering the answer, immediately continue the active task from the exact point it was paused. Do not ask for permission to resume unless the aside answer revealed a blocker or a reason to reconsider the current approach (see Edge Cases).
---
## Edge Cases
**No question provided (`/aside` with nothing after it):**
Respond:
```
ASIDE: no question provided
What would you like to know? (ask your question and I'll answer without losing the current task context)
— Back to task: [one-line description of what was being done]
```
**Question reveals a potential problem with the current task:**
Flag it clearly before resuming:
```
ASIDE: [answer]
⚠️ Note: This answer suggests [issue] with the current approach. Want to address this before continuing, or proceed as planned?
```
Wait for the user's decision before resuming.
**Question is actually a task redirect (not a side question):**
If the question implies changing what is being built (e.g., `/aside actually, let's use Redis instead`), clarify:
```
ASIDE: That sounds like a direction change, not just a side question.
Do you want to:
(a) Answer this as information only and keep the current plan
(b) Pause the current task and change approach
```
Wait for the user's answer — do not make assumptions.
**Question is about the currently open file or code:**
Answer from the live context. If the file was read earlier in the session, reference it directly. If not, read it now (read-only) and answer with a file:line reference.
**No active task (nothing in progress when `/aside` is invoked):**
Still use the standard wrapper so the response shape stays consistent:
```
ASIDE: [restate the question briefly]
[Your answer here]
— Back to task: no active task to resume
```
**Question requires a long answer:**
Give the essential answer concisely, then offer:
```
That's the short version. Want a deeper explanation after we finish [current task]?
```
**Multiple `/aside` questions in a row:**
Answer each one in sequence. After the last answer, resume the main task. Do not lose task state across a chain of asides.
**Aside answer implies a code change is needed:**
Note the change needed but do not make it during the aside:
```
ASIDE: [answer]
📝 Worth fixing: [what should be changed]. I'll flag this after the current task unless you want to address it now.
```
**Question is ambiguous or too vague:**
Ask one clarifying question — the shortest question that gets the information needed to answer. Do not ask multiple questions.
---
## Example Output
```
User: /aside what does fetchWithRetry() actually do?
ASIDE: what does fetchWithRetry() do?
fetchWithRetry() (src/api/retry.ts:12) attempts the request up to 3 times with
exponential backoff (250ms → 500ms → 1s). It only retries on 5xx responses and
network errors — 4xx errors are treated as final and not retried.
— Back to task: refactoring the auth middleware in src/middleware/auth.ts
```
```
User: /aside is the approach we're taking thread-safe?
ASIDE: is the current approach thread-safe?
No — the shared cache object in src/cache/store.ts:34 is mutated without locking.
Under concurrent requests this is a race condition. It's low risk in a single-process
Node.js server but would be a real problem with worker threads or clustering.
⚠️ Note: This could affect the feature we're building. Want to address this now or continue and fix it in a follow-up?
```
---
## Notes
- Never modify files during an aside — read-only access only
- The aside is a conversation pause, not a new task — the original task must always resume
- Keep answers focused: the goal is to unblock the user quickly, not to deliver a lecture
- If an aside sparks a larger discussion, finish the current task first unless the aside reveals a blocker
- Asides are not saved to session files unless explicitly relevant to the task outcome

62
.agent/knowledge/everything_claude/commands/build-fix.md Normal file
View File

@@ -0,0 +1,62 @@
# Build and Fix
Incrementally fix build and type errors with minimal, safe changes.
## Step 1: Detect Build System
Identify the project's build tool and run the build:
| Indicator | Build Command |
|-----------|---------------|
| `package.json` with `build` script | `npm run build` or `pnpm build` |
| `tsconfig.json` (TypeScript only) | `npx tsc --noEmit` |
| `Cargo.toml` | `cargo build 2>&1` |
| `pom.xml` | `mvn compile` |
| `build.gradle` | `./gradlew compileJava` |
| `go.mod` | `go build ./...` |
| `pyproject.toml` | `python -m compileall -q .` or `mypy .` |
## Step 2: Parse and Group Errors
1. Run the build command and capture stderr
2. Group errors by file path
3. Sort by dependency order (fix imports/types before logic errors)
4. Count total errors for progress tracking
## Step 3: Fix Loop (One Error at a Time)
For each error:
1. **Read the file** — Use Read tool to see error context (10 lines around the error)
2. **Diagnose** — Identify root cause (missing import, wrong type, syntax error)
3. **Fix minimally** — Use Edit tool for the smallest change that resolves the error
4. **Re-run build** — Verify the error is gone and no new errors introduced
5. **Move to next** — Continue with remaining errors
## Step 4: Guardrails
Stop and ask the user if:
- A fix introduces **more errors than it resolves**
- The **same error persists after 3 attempts** (likely a deeper issue)
- The fix requires **architectural changes** (not just a build fix)
- Build errors stem from **missing dependencies** (need `npm install`, `cargo add`, etc.)
## Step 5: Summary
Show results:
- Errors fixed (with file paths)
- Errors remaining (if any)
- New errors introduced (should be zero)
- Suggested next steps for unresolved issues
## Recovery Strategies
| Situation | Action |
|-----------|--------|
| Missing module/import | Check if package is installed; suggest install command |
| Type mismatch | Read both type definitions; fix the narrower type |
| Circular dependency | Identify cycle with import graph; suggest extraction |
| Version conflict | Check `package.json` / `Cargo.toml` for version constraints |
| Build tool misconfiguration | Read config file; compare with working defaults |
Fix one error at a time for safety. Prefer minimal diffs over refactoring.

74
.agent/knowledge/everything_claude/commands/checkpoint.md Normal file
View File

@@ -0,0 +1,74 @@
# Checkpoint Command
Create or verify a checkpoint in your workflow.
## Usage
`/checkpoint [create|verify|list] [name]`
## Create Checkpoint
When creating a checkpoint:
1. Run `/verify quick` to ensure current state is clean
2. Create a git stash or commit with checkpoint name
3. Log checkpoint to `.claude/checkpoints.log`:
```bash
echo "$(date +%Y-%m-%d-%H:%M) | $CHECKPOINT_NAME | $(git rev-parse --short HEAD)" >> .claude/checkpoints.log
```
4. Report checkpoint created
## Verify Checkpoint
When verifying against a checkpoint:
1. Read checkpoint from log
2. Compare current state to checkpoint:
- Files added since checkpoint
- Files modified since checkpoint
- Test pass rate now vs then
- Coverage now vs then
3. Report:
```
CHECKPOINT COMPARISON: $NAME
============================
Files changed: X
Tests: +Y passed / -Z failed
Coverage: +X% / -Y%
Build: [PASS/FAIL]
```
## List Checkpoints
Show all checkpoints with:
- Name
- Timestamp
- Git SHA
- Status (current, behind, ahead)
## Workflow
Typical checkpoint flow:
```
[Start] --> /checkpoint create "feature-start"
|
[Implement] --> /checkpoint create "core-done"
|
[Test] --> /checkpoint verify "core-done"
|
[Refactor] --> /checkpoint create "refactor-done"
|
[PR] --> /checkpoint verify "feature-start"
```
## Arguments
$ARGUMENTS:
- `create <name>` - Create named checkpoint
- `verify <name>` - Verify against named checkpoint
- `list` - Show all checkpoints
- `clear` - Remove old checkpoints (keeps last 5)

51
.agent/knowledge/everything_claude/commands/claw.md Normal file
View File

@@ -0,0 +1,51 @@
---
description: Start NanoClaw v2 — ECC's persistent, zero-dependency REPL with model routing, skill hot-load, branching, compaction, export, and metrics.
---
# Claw Command
Start an interactive AI agent session with persistent markdown history and operational controls.
## Usage
```bash
node scripts/claw.js
```
Or via npm:
```bash
npm run claw
```
## Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `CLAW_SESSION` | `default` | Session name (alphanumeric + hyphens) |
| `CLAW_SKILLS` | *(empty)* | Comma-separated skills loaded at startup |
| `CLAW_MODEL` | `sonnet` | Default model for the session |
## REPL Commands
```text
/help Show help
/clear Clear current session history
/history Print full conversation history
/sessions List saved sessions
/model [name] Show/set model
/load <skill-name> Hot-load a skill into context
/branch <session-name> Branch current session
/search <query> Search query across sessions
/compact Compact old turns, keep recent context
/export <md|json|txt> [path] Export session
/metrics Show session metrics
exit Quit
```
## Notes
- NanoClaw remains zero-dependency.
- Sessions are stored at `~/.claude/claw/<session>.md`.
- Compaction keeps the most recent turns and writes a compaction header.
- Export supports markdown, JSON turns, and plain text.

40
.agent/knowledge/everything_claude/commands/code-review.md Normal file
View File

@@ -0,0 +1,40 @@
# Code Review
Comprehensive security and quality review of uncommitted changes:
1. Get changed files: git diff --name-only HEAD
2. For each changed file, check for:
**Security Issues (CRITICAL):**
- Hardcoded credentials, API keys, tokens
- SQL injection vulnerabilities
- XSS vulnerabilities
- Missing input validation
- Insecure dependencies
- Path traversal risks
**Code Quality (HIGH):**
- Functions > 50 lines
- Files > 800 lines
- Nesting depth > 4 levels
- Missing error handling
- console.log statements
- TODO/FIXME comments
- Missing JSDoc for public APIs
**Best Practices (MEDIUM):**
- Mutation patterns (use immutable instead)
- Emoji usage in code/comments
- Missing tests for new code
- Accessibility issues (a11y)
3. Generate report with:
- Severity: CRITICAL, HIGH, MEDIUM, LOW
- File location and line numbers
- Issue description
- Suggested fix
4. Block commit if CRITICAL or HIGH issues found
Never approve code with security vulnerabilities!

29
.agent/knowledge/everything_claude/commands/context-budget.md Normal file
View File

@@ -0,0 +1,29 @@
---
description: Analyze context window usage across agents, skills, MCP servers, and rules to find optimization opportunities. Helps reduce token overhead and avoid performance warnings.
---
# Context Budget Optimizer
Analyze your Claude Code setup's context window consumption and produce actionable recommendations to reduce token overhead.
## Usage
```
/context-budget [--verbose]
```
- Default: summary with top recommendations
- `--verbose`: full breakdown per component
$ARGUMENTS
## What to Do
Run the **context-budget** skill (`skills/context-budget/SKILL.md`) with the following inputs:
1. Pass `--verbose` flag if present in `$ARGUMENTS`
2. Assume a 200K context window (Claude Sonnet default) unless the user specifies otherwise
3. Follow the skill's four phases: Inventory → Classify → Detect Issues → Report
4. Output the formatted Context Budget Report to the user
The skill handles all scanning logic, token estimation, issue detection, and report formatting.

173
.agent/knowledge/everything_claude/commands/cpp-build.md Normal file
View File

@@ -0,0 +1,173 @@
---
description: Fix C++ build errors, CMake issues, and linker problems incrementally. Invokes the cpp-build-resolver agent for minimal, surgical fixes.
---
# C++ Build and Fix
This command invokes the **cpp-build-resolver** agent to incrementally fix C++ build errors with minimal changes.
## What This Command Does
1. **Run Diagnostics**: Execute `cmake --build`, `clang-tidy`, `cppcheck`
2. **Parse Errors**: Group by file and sort by severity
3. **Fix Incrementally**: One error at a time
4. **Verify Each Fix**: Re-run build after each change
5. **Report Summary**: Show what was fixed and what remains
## When to Use
Use `/cpp-build` when:
- `cmake --build build` fails with errors
- Linker errors (undefined references, multiple definitions)
- Template instantiation failures
- Include/dependency issues
- After pulling changes that break the build
## Diagnostic Commands Run
```bash
# CMake configure
cmake -B build -S .
# Build
cmake --build build 2>&1 | head -100
# Static analysis (if available)
clang-tidy src/*.cpp -- -std=c++17
cppcheck --enable=all src/
```
## Example Session
```text
User: /cpp-build
Agent:
# C++ Build Resolution
## Initial Diagnostics
```bash
$ cmake --build build
src/service/user.cpp:25:15: error: use of undeclared identifier 'UserRepository'
src/handler/api.cpp:42:9: error: no matching function for call to 'process'
src/handler/api.cpp:58:1: error: non-void function does not return a value
```
Errors found: 3
## Fix 1: Undeclared Identifier
File: src/service/user.cpp:25
Error: use of undeclared identifier 'UserRepository'
Cause: Missing include
```cpp
// Added include
#include "repository/user_repository.hpp"
```
```bash
$ cmake --build build
# 2 errors remaining
```
## Fix 2: No Matching Function
File: src/handler/api.cpp:42
Error: no matching function for call to 'process'
```cpp
// Changed
process(params.get("count"));
// To
process(std::stoi(params.get("count")));
```
```bash
$ cmake --build build
# 1 error remaining
```
## Fix 3: Missing Return
File: src/handler/api.cpp:58
Error: non-void function does not return a value
```cpp
std::optional<User> getUser(const std::string& id) {
if (id.empty()) {
return std::nullopt;
}
auto user = findUser(id);
// Added missing return
return user;
}
```
```bash
$ cmake --build build
# Build successful!
```
## Final Verification
```bash
$ ctest --test-dir build --output-on-failure
Test project build
1/5 Test #1: unit_tests ........ Passed 0.02 sec
2/5 Test #2: integration_tests Passed 0.15 sec
All tests passed.
```
## Summary
| Metric | Count |
|--------|-------|
| Build errors fixed | 3 |
| Linker errors fixed | 0 |
| Files modified | 2 |
| Remaining issues | 0 |
Build Status: ✅ SUCCESS
```
## Common Errors Fixed
| Error | Typical Fix |
|-------|-------------|
| `undeclared identifier` | Add `#include` or fix typo |
| `no matching function` | Fix argument types or add overload |
| `undefined reference` | Link library or add implementation |
| `multiple definition` | Use `inline` or move to .cpp |
| `incomplete type` | Replace forward decl with `#include` |
| `no member named X` | Fix member name or include |
| `cannot convert X to Y` | Add appropriate cast |
| `CMake Error` | Fix CMakeLists.txt configuration |
## Fix Strategy
1. **Compilation errors first** - Code must compile
2. **Linker errors second** - Resolve undefined references
3. **Warnings third** - Fix with `-Wall -Wextra`
4. **One fix at a time** - Verify each change
5. **Minimal changes** - Don't refactor, just fix
## Stop Conditions
The agent will stop and report if:
- Same error persists after 3 attempts
- Fix introduces more errors
- Requires architectural changes
- Missing external dependencies
## Related Commands
- `/cpp-test` - Run tests after build succeeds
- `/cpp-review` - Review code quality
- `/verify` - Full verification loop
## Related
- Agent: `agents/cpp-build-resolver.md`
- Skill: `skills/cpp-coding-standards/`

132
.agent/knowledge/everything_claude/commands/cpp-review.md Normal file
View File

@@ -0,0 +1,132 @@
---
description: Comprehensive C++ code review for memory safety, modern C++ idioms, concurrency, and security. Invokes the cpp-reviewer agent.
---
# C++ Code Review
This command invokes the **cpp-reviewer** agent for comprehensive C++-specific code review.
## What This Command Does
1. **Identify C++ Changes**: Find modified `.cpp`, `.hpp`, `.cc`, `.h` files via `git diff`
2. **Run Static Analysis**: Execute `clang-tidy` and `cppcheck`
3. **Memory Safety Scan**: Check for raw new/delete, buffer overflows, use-after-free
4. **Concurrency Review**: Analyze thread safety, mutex usage, data races
5. **Modern C++ Check**: Verify code follows C++17/20 conventions and best practices
6. **Generate Report**: Categorize issues by severity
## When to Use
Use `/cpp-review` when:
- After writing or modifying C++ code
- Before committing C++ changes
- Reviewing pull requests with C++ code
- Onboarding to a new C++ codebase
- Checking for memory safety issues
## Review Categories
### CRITICAL (Must Fix)
- Raw `new`/`delete` without RAII
- Buffer overflows and use-after-free
- Data races without synchronization
- Command injection via `system()`
- Uninitialized variable reads
- Null pointer dereferences
### HIGH (Should Fix)
- Rule of Five violations
- Missing `std::lock_guard` / `std::scoped_lock`
- Detached threads without proper lifetime management
- C-style casts instead of `static_cast`/`dynamic_cast`
- Missing `const` correctness
### MEDIUM (Consider)
- Unnecessary copies (pass by value instead of `const&`)
- Missing `reserve()` on known-size containers
- `using namespace std;` in headers
- Missing `[[nodiscard]]` on important return values
- Overly complex template metaprogramming
## Automated Checks Run
```bash
# Static analysis
clang-tidy --checks='*,-llvmlibc-*' src/*.cpp -- -std=c++17
# Additional analysis
cppcheck --enable=all --suppress=missingIncludeSystem src/
# Build with warnings
cmake --build build -- -Wall -Wextra -Wpedantic
```
## Example Usage
```text
User: /cpp-review
Agent:
# C++ Code Review Report
## Files Reviewed
- src/handler/user.cpp (modified)
- src/service/auth.cpp (modified)
## Static Analysis Results
✓ clang-tidy: 2 warnings
✓ cppcheck: No issues
## Issues Found
[CRITICAL] Memory Leak
File: src/service/auth.cpp:45
Issue: Raw `new` without matching `delete`
```cpp
auto* session = new Session(userId); // Memory leak!
cache[userId] = session;
```
Fix: Use `std::unique_ptr`
```cpp
auto session = std::make_unique<Session>(userId);
cache[userId] = std::move(session);
```
[HIGH] Missing const Reference
File: src/handler/user.cpp:28
Issue: Large object passed by value
```cpp
void processUser(User user) { // Unnecessary copy
```
Fix: Pass by const reference
```cpp
void processUser(const User& user) {
```
## Summary
- CRITICAL: 1
- HIGH: 1
- MEDIUM: 0
Recommendation: ❌ Block merge until CRITICAL issue is fixed
```
## Approval Criteria
| Status | Condition |
|--------|-----------|
| ✅ Approve | No CRITICAL or HIGH issues |
| ⚠️ Warning | Only MEDIUM issues (merge with caution) |
| ❌ Block | CRITICAL or HIGH issues found |
## Integration with Other Commands
- Use `/cpp-test` first to ensure tests pass
- Use `/cpp-build` if build errors occur
- Use `/cpp-review` before committing
- Use `/code-review` for non-C++ specific concerns
## Related
- Agent: `agents/cpp-reviewer.md`
- Skills: `skills/cpp-coding-standards/`, `skills/cpp-testing/`

251
.agent/knowledge/everything_claude/commands/cpp-test.md Normal file
View File

@@ -0,0 +1,251 @@
---
description: Enforce TDD workflow for C++. Write GoogleTest tests first, then implement. Verify coverage with gcov/lcov.
---
# C++ TDD Command
This command enforces test-driven development methodology for C++ code using GoogleTest/GoogleMock with CMake/CTest.
## What This Command Does
1. **Define Interfaces**: Scaffold class/function signatures first
2. **Write Tests**: Create comprehensive GoogleTest test cases (RED)
3. **Run Tests**: Verify tests fail for the right reason
4. **Implement Code**: Write minimal code to pass (GREEN)
5. **Refactor**: Improve while keeping tests green
6. **Check Coverage**: Ensure 80%+ coverage
## When to Use
Use `/cpp-test` when:
- Implementing new C++ functions or classes
- Adding test coverage to existing code
- Fixing bugs (write failing test first)
- Building critical business logic
- Learning TDD workflow in C++
## TDD Cycle
```
RED → Write failing GoogleTest test
GREEN → Implement minimal code to pass
REFACTOR → Improve code, tests stay green
REPEAT → Next test case
```
## Example Session
````
User: /cpp-test I need a function to validate email addresses
Agent:
# TDD Session: Email Validator
## Step 1: Define Interface
```cpp
// validator/email.hpp
#pragma once
#include <string>
#include <expected>
enum class EmailError {
Empty,
InvalidFormat
};
std::expected<void, EmailError> validate_email(const std::string& email);
```
## Step 2: Write Tests (RED)
```cpp
// validator/email_test.cpp
#include <gtest/gtest.h>
#include "email.hpp"
TEST(ValidateEmail, AcceptsSimpleEmail) {
auto result = validate_email("user@example.com");
EXPECT_TRUE(result.has_value());
}
TEST(ValidateEmail, AcceptsSubdomain) {
EXPECT_TRUE(validate_email("user@mail.example.com").has_value());
}
TEST(ValidateEmail, AcceptsPlus) {
EXPECT_TRUE(validate_email("user+tag@example.com").has_value());
}
TEST(ValidateEmail, RejectsEmpty) {
auto result = validate_email("");
ASSERT_FALSE(result.has_value());
EXPECT_EQ(result.error(), EmailError::Empty);
}
TEST(ValidateEmail, RejectsNoAtSign) {
EXPECT_FALSE(validate_email("userexample.com").has_value());
}
TEST(ValidateEmail, RejectsNoDomain) {
EXPECT_FALSE(validate_email("user@").has_value());
}
TEST(ValidateEmail, RejectsNoLocalPart) {
EXPECT_FALSE(validate_email("@example.com").has_value());
}
```
## Step 3: Run Tests - Verify FAIL
```bash
$ cmake --build build && ctest --test-dir build --output-on-failure
1/1 Test #1: email_validator_test .....***Failed
--- undefined reference to `validate_email`
FAIL
```
✓ Tests fail as expected (unimplemented).
## Step 4: Implement Minimal Code (GREEN)
```cpp
// validator/email.cpp
#include "email.hpp"
#include <regex>
std::expected<void, EmailError> validate_email(const std::string& email) {
if (email.empty()) {
return std::unexpected(EmailError::Empty);
}
static const std::regex pattern(R"([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})");
if (!std::regex_match(email, pattern)) {
return std::unexpected(EmailError::InvalidFormat);
}
return {};
}
```
## Step 5: Run Tests - Verify PASS
```bash
$ cmake --build build && ctest --test-dir build --output-on-failure
1/1 Test #1: email_validator_test ..... Passed 0.01 sec
100% tests passed.
```
✓ All tests passing!
## Step 6: Check Coverage
```bash
$ cmake -DCMAKE_CXX_FLAGS="--coverage" -B build && cmake --build build
$ ctest --test-dir build
$ lcov --capture --directory build --output-file coverage.info
$ lcov --list coverage.info
validator/email.cpp | 100%
```
✓ Coverage: 100%
## TDD Complete!
````
## Test Patterns
### Basic Tests
```cpp
TEST(SuiteName, TestName) {
EXPECT_EQ(add(2, 3), 5);
EXPECT_NE(result, nullptr);
EXPECT_TRUE(is_valid);
EXPECT_THROW(func(), std::invalid_argument);
}
```
### Fixtures
```cpp
class DatabaseTest : public ::testing::Test {
protected:
void SetUp() override { db_ = create_test_db(); }
void TearDown() override { db_.reset(); }
std::unique_ptr<Database> db_;
};
TEST_F(DatabaseTest, InsertsRecord) {
db_->insert("key", "value");
EXPECT_EQ(db_->get("key"), "value");
}
```
### Parameterized Tests
```cpp
class PrimeTest : public ::testing::TestWithParam<std::pair<int, bool>> {};
TEST_P(PrimeTest, ChecksPrimality) {
auto [input, expected] = GetParam();
EXPECT_EQ(is_prime(input), expected);
}
INSTANTIATE_TEST_SUITE_P(Primes, PrimeTest, ::testing::Values(
std::make_pair(2, true),
std::make_pair(4, false),
std::make_pair(7, true)
));
```
## Coverage Commands
```bash
# Build with coverage
cmake -DCMAKE_CXX_FLAGS="--coverage" -DCMAKE_EXE_LINKER_FLAGS="--coverage" -B build
# Run tests
cmake --build build && ctest --test-dir build
# Generate coverage report
lcov --capture --directory build --output-file coverage.info
lcov --remove coverage.info '/usr/*' --output-file coverage.info
genhtml coverage.info --output-directory coverage_html
```
## Coverage Targets
| Code Type | Target |
|-----------|--------|
| Critical business logic | 100% |
| Public APIs | 90%+ |
| General code | 80%+ |
| Generated code | Exclude |
## TDD Best Practices
**DO:**
- Write test FIRST, before any implementation
- Run tests after each change
- Use `EXPECT_*` (continues) over `ASSERT_*` (stops) when appropriate
- Test behavior, not implementation details
- Include edge cases (empty, null, max values, boundary conditions)
**DON'T:**
- Write implementation before tests
- Skip the RED phase
- Test private methods directly (test through public API)
- Use `sleep` in tests
- Ignore flaky tests
## Related Commands
- `/cpp-build` - Fix build errors
- `/cpp-review` - Review code after implementation
- `/verify` - Run full verification loop
## Related
- Skill: `skills/cpp-testing/`
- Skill: `skills/tdd-workflow/`

92
.agent/knowledge/everything_claude/commands/devfleet.md Normal file
View File

@@ -0,0 +1,92 @@
---
description: Orchestrate parallel Claude Code agents via Claude DevFleet — plan projects from natural language, dispatch agents in isolated worktrees, monitor progress, and read structured reports.
---
# DevFleet — Multi-Agent Orchestration
Orchestrate parallel Claude Code agents via Claude DevFleet. Each agent runs in an isolated git worktree with full tooling.
Requires the DevFleet MCP server: `claude mcp add devfleet --transport http http://localhost:18801/mcp`
## Flow
```
User describes project
→ plan_project(prompt) → mission DAG with dependencies
→ Show plan, get approval
→ dispatch_mission(M1) → Agent spawns in worktree
→ M1 completes → auto-merge → M2 auto-dispatches (depends_on M1)
→ M2 completes → auto-merge
→ get_report(M2) → files_changed, what_done, errors, next_steps
→ Report summary to user
```
## Workflow
1. **Plan the project** from the user's description:
```
mcp__devfleet__plan_project(prompt="<user's description>")
```
This returns a project with chained missions. Show the user:
- Project name and ID
- Each mission: title, type, dependencies
- The dependency DAG (which missions block which)
2. **Wait for user approval** before dispatching. Show the plan clearly.
3. **Dispatch the first mission** (the one with empty `depends_on`):
```
mcp__devfleet__dispatch_mission(mission_id="<first_mission_id>")
```
The remaining missions auto-dispatch as their dependencies complete (because `plan_project` creates them with `auto_dispatch=true`). When manually creating missions with `create_mission`, you must explicitly set `auto_dispatch=true` for this behavior.
4. **Monitor progress** — check what's running:
```
mcp__devfleet__get_dashboard()
```
Or check a specific mission:
```
mcp__devfleet__get_mission_status(mission_id="<id>")
```
Prefer polling with `get_mission_status` over `wait_for_mission` for long-running missions, so the user sees progress updates.
5. **Read the report** for each completed mission:
```
mcp__devfleet__get_report(mission_id="<mission_id>")
```
Call this for every mission that reached a terminal state. Reports contain: files_changed, what_done, what_open, what_tested, what_untested, next_steps, errors_encountered.
## All Available Tools
| Tool | Purpose |
|------|---------|
| `plan_project(prompt)` | AI breaks description into chained missions with `auto_dispatch=true` |
| `create_project(name, path?, description?)` | Create a project manually, returns `project_id` |
| `create_mission(project_id, title, prompt, depends_on?, auto_dispatch?)` | Add a mission. `depends_on` is a list of mission ID strings. |
| `dispatch_mission(mission_id, model?, max_turns?)` | Start an agent |
| `cancel_mission(mission_id)` | Stop a running agent |
| `wait_for_mission(mission_id, timeout_seconds?)` | Block until done (prefer polling for long tasks) |
| `get_mission_status(mission_id)` | Check progress without blocking |
| `get_report(mission_id)` | Read structured report |
| `get_dashboard()` | System overview |
| `list_projects()` | Browse projects |
| `list_missions(project_id, status?)` | List missions |
## Guidelines
- Always confirm the plan before dispatching unless the user said "go ahead"
- Include mission titles and IDs when reporting status
- If a mission fails, read its report to understand errors before retrying
- Agent concurrency is configurable (default: 3). Excess missions queue and auto-dispatch as slots free up. Check `get_dashboard()` for slot availability.
- Dependencies form a DAG — never create circular dependencies
- Each agent auto-merges its worktree on completion. If a merge conflict occurs, the changes remain on the worktree branch for manual resolution.

31
.agent/knowledge/everything_claude/commands/docs.md Normal file
View File

@@ -0,0 +1,31 @@
---
description: Look up current documentation for a library or topic via Context7.
---
# /docs
## Purpose
Look up up-to-date documentation for a library, framework, or API and return a summarized answer with relevant code snippets. Uses the Context7 MCP (resolve-library-id and query-docs) so answers reflect current docs, not training data.
## Usage
```
/docs [library name] [question]
```
Use quotes for multi-word arguments so they are parsed as a single token. Example: `/docs "Next.js" "How do I configure middleware?"`
If library or question is omitted, prompt the user for:
1. The library or product name (e.g. Next.js, Prisma, Supabase).
2. The specific question or task (e.g. "How do I set up middleware?", "Auth methods").
## Workflow
1. **Resolve library ID** — Call the Context7 tool `resolve-library-id` with the library name and the user's question to get a Context7-compatible library ID (e.g. `/vercel/next.js`).
2. **Query docs** — Call `query-docs` with that library ID and the user's question.
3. **Summarize** — Return a concise answer and include relevant code examples from the fetched documentation. Mention the library (and version if relevant).
## Output
The user receives a short, accurate answer backed by current docs, plus any code snippets that help. If Context7 is not available, say so and answer from training data with a note that docs may be outdated.

365
.agent/knowledge/everything_claude/commands/e2e.md Normal file
View File

@@ -0,0 +1,365 @@
---
description: Generate and run end-to-end tests with Playwright. Creates test journeys, runs tests, captures screenshots/videos/traces, and uploads artifacts.
---
# E2E Command
This command invokes the **e2e-runner** agent to generate, maintain, and execute end-to-end tests using Playwright.
## What This Command Does
1. **Generate Test Journeys** - Create Playwright tests for user flows
2. **Run E2E Tests** - Execute tests across browsers
3. **Capture Artifacts** - Screenshots, videos, traces on failures
4. **Upload Results** - HTML reports and JUnit XML
5. **Identify Flaky Tests** - Quarantine unstable tests
## When to Use
Use `/e2e` when:
- Testing critical user journeys (login, trading, payments)
- Verifying multi-step flows work end-to-end
- Testing UI interactions and navigation
- Validating integration between frontend and backend
- Preparing for production deployment
## How It Works
The e2e-runner agent will:
1. **Analyze user flow** and identify test scenarios
2. **Generate Playwright test** using Page Object Model pattern
3. **Run tests** across multiple browsers (Chrome, Firefox, Safari)
4. **Capture failures** with screenshots, videos, and traces
5. **Generate report** with results and artifacts
6. **Identify flaky tests** and recommend fixes
## Example Usage
```
User: /e2e Test the market search and view flow
Agent (e2e-runner):
# E2E Test Generation: Market Search and View Flow
## Test Scenario Identified
**User Journey:** Market Search → View Results → Click Market → View Details
**Test Coverage:**
1. Navigate to markets page
2. Perform semantic search
3. Verify search results
4. Click on first result
5. Verify market details page loads
6. Verify chart renders
## Generated Test Code
```typescript
// tests/e2e/markets/search-and-view.spec.ts
import { test, expect } from '@playwright/test'
import { MarketsPage } from '../../pages/MarketsPage'
import { MarketDetailsPage } from '../../pages/MarketDetailsPage'
test.describe('Market Search and View Flow', () => {
test('user can search markets and view details', async ({ page }) => {
// 1. Navigate to markets page
const marketsPage = new MarketsPage(page)
await marketsPage.goto()
// Verify page loaded
await expect(page).toHaveTitle(/Markets/)
await expect(page.locator('h1')).toContainText('Markets')
// 2. Perform semantic search
await marketsPage.searchMarkets('election')
// Wait for API response
await page.waitForResponse(resp =>
resp.url().includes('/api/markets/search') && resp.status() === 200
)
// 3. Verify search results
const marketCards = marketsPage.marketCards
await expect(marketCards.first()).toBeVisible()
const resultCount = await marketCards.count()
expect(resultCount).toBeGreaterThan(0)
// Take screenshot of search results
await page.screenshot({ path: 'artifacts/search-results.png' })
// 4. Click on first result
const firstMarketTitle = await marketCards.first().textContent()
await marketCards.first().click()
// 5. Verify market details page loads
await expect(page).toHaveURL(/\/markets\/[a-z0-9-]+/)
const detailsPage = new MarketDetailsPage(page)
await expect(detailsPage.marketName).toBeVisible()
await expect(detailsPage.marketDescription).toBeVisible()
// 6. Verify chart renders
await expect(detailsPage.priceChart).toBeVisible()
// Verify market name matches
const detailsTitle = await detailsPage.marketName.textContent()
expect(detailsTitle?.toLowerCase()).toContain(
firstMarketTitle?.toLowerCase().substring(0, 20) || ''
)
// Take screenshot of market details
await page.screenshot({ path: 'artifacts/market-details.png' })
})
test('search with no results shows empty state', async ({ page }) => {
const marketsPage = new MarketsPage(page)
await marketsPage.goto()
// Search for non-existent market
await marketsPage.searchMarkets('xyznonexistentmarket123456')
// Verify empty state
await expect(page.locator('[data-testid="no-results"]')).toBeVisible()
await expect(page.locator('[data-testid="no-results"]')).toContainText(
/no.*results|no.*markets/i
)
const marketCount = await marketsPage.marketCards.count()
expect(marketCount).toBe(0)
})
test('can clear search and see all markets again', async ({ page }) => {
const marketsPage = new MarketsPage(page)
await marketsPage.goto()
// Initial market count
const initialCount = await marketsPage.marketCards.count()
// Perform search
await marketsPage.searchMarkets('trump')
await page.waitForLoadState('networkidle')
// Verify filtered results
const filteredCount = await marketsPage.marketCards.count()
expect(filteredCount).toBeLessThan(initialCount)
// Clear search
await marketsPage.searchInput.clear()
await page.waitForLoadState('networkidle')
// Verify all markets shown again
const finalCount = await marketsPage.marketCards.count()
expect(finalCount).toBe(initialCount)
})
})
```
## Running Tests
```bash
# Run the generated test
npx playwright test tests/e2e/markets/search-and-view.spec.ts
Running 3 tests using 3 workers
✓ [chromium] › search-and-view.spec.ts:5:3 › user can search markets and view details (4.2s)
✓ [chromium] › search-and-view.spec.ts:52:3 › search with no results shows empty state (1.8s)
✓ [chromium] › search-and-view.spec.ts:67:3 › can clear search and see all markets again (2.9s)
3 passed (9.1s)
Artifacts generated:
- artifacts/search-results.png
- artifacts/market-details.png
- playwright-report/index.html
```
## Test Report
```
╔══════════════════════════════════════════════════════════════╗
║ E2E Test Results ║
╠══════════════════════════════════════════════════════════════╣
║ Status: ✅ ALL TESTS PASSED ║
║ Total: 3 tests ║
║ Passed: 3 (100%) ║
║ Failed: 0 ║
║ Flaky: 0 ║
║ Duration: 9.1s ║
╚══════════════════════════════════════════════════════════════╝
Artifacts:
📸 Screenshots: 2 files
📹 Videos: 0 files (only on failure)
🔍 Traces: 0 files (only on failure)
📊 HTML Report: playwright-report/index.html
View report: npx playwright show-report
```
✅ E2E test suite ready for CI/CD integration!
```
## Test Artifacts
When tests run, the following artifacts are captured:
**On All Tests:**
- HTML Report with timeline and results
- JUnit XML for CI integration
**On Failure Only:**
- Screenshot of the failing state
- Video recording of the test
- Trace file for debugging (step-by-step replay)
- Network logs
- Console logs
## Viewing Artifacts
```bash
# View HTML report in browser
npx playwright show-report
# View specific trace file
npx playwright show-trace artifacts/trace-abc123.zip
# Screenshots are saved in artifacts/ directory
open artifacts/search-results.png
```
## Flaky Test Detection
If a test fails intermittently:
```
⚠️ FLAKY TEST DETECTED: tests/e2e/markets/trade.spec.ts
Test passed 7/10 runs (70% pass rate)
Common failure:
"Timeout waiting for element '[data-testid="confirm-btn"]'"
Recommended fixes:
1. Add explicit wait: await page.waitForSelector('[data-testid="confirm-btn"]')
2. Increase timeout: { timeout: 10000 }
3. Check for race conditions in component
4. Verify element is not hidden by animation
Quarantine recommendation: Mark as test.fixme() until fixed
```
## Browser Configuration
Tests run on multiple browsers by default:
- ✅ Chromium (Desktop Chrome)
- ✅ Firefox (Desktop)
- ✅ WebKit (Desktop Safari)
- ✅ Mobile Chrome (optional)
Configure in `playwright.config.ts` to adjust browsers.
## CI/CD Integration
Add to your CI pipeline:
```yaml
# .github/workflows/e2e.yml
- name: Install Playwright
run: npx playwright install --with-deps
- name: Run E2E tests
run: npx playwright test
- name: Upload artifacts
if: always()
uses: actions/upload-artifact@v3
with:
name: playwright-report
path: playwright-report/
```
## PMX-Specific Critical Flows
For PMX, prioritize these E2E tests:
**🔴 CRITICAL (Must Always Pass):**
1. User can connect wallet
2. User can browse markets
3. User can search markets (semantic search)
4. User can view market details
5. User can place trade (with test funds)
6. Market resolves correctly
7. User can withdraw funds
**🟡 IMPORTANT:**
1. Market creation flow
2. User profile updates
3. Real-time price updates
4. Chart rendering
5. Filter and sort markets
6. Mobile responsive layout
## Best Practices
**DO:**
- ✅ Use Page Object Model for maintainability
- ✅ Use data-testid attributes for selectors
- ✅ Wait for API responses, not arbitrary timeouts
- ✅ Test critical user journeys end-to-end
- ✅ Run tests before merging to main
- ✅ Review artifacts when tests fail
**DON'T:**
- ❌ Use brittle selectors (CSS classes can change)
- ❌ Test implementation details
- ❌ Run tests against production
- ❌ Ignore flaky tests
- ❌ Skip artifact review on failures
- ❌ Test every edge case with E2E (use unit tests)
## Important Notes
**CRITICAL for PMX:**
- E2E tests involving real money MUST run on testnet/staging only
- Never run trading tests against production
- Set `test.skip(process.env.NODE_ENV === 'production')` for financial tests
- Use test wallets with small test funds only
## Integration with Other Commands
- Use `/plan` to identify critical journeys to test
- Use `/tdd` for unit tests (faster, more granular)
- Use `/e2e` for integration and user journey tests
- Use `/code-review` to verify test quality
## Related Agents
This command invokes the `e2e-runner` agent provided by ECC.
For manual installs, the source file lives at:
`agents/e2e-runner.md`
## Quick Commands
```bash
# Run all E2E tests
npx playwright test
# Run specific test file
npx playwright test tests/e2e/markets/search.spec.ts
# Run in headed mode (see browser)
npx playwright test --headed
# Debug test
npx playwright test --debug
# Generate test code
npx playwright codegen http://localhost:3000
# View report
npx playwright show-report
```

120
.agent/knowledge/everything_claude/commands/eval.md Normal file
View File

@@ -0,0 +1,120 @@
# Eval Command
Manage eval-driven development workflow.
## Usage
`/eval [define|check|report|list] [feature-name]`
## Define Evals
`/eval define feature-name`
Create a new eval definition:
1. Create `.claude/evals/feature-name.md` with template:
```markdown
## EVAL: feature-name
Created: $(date)
### Capability Evals
- [ ] [Description of capability 1]
- [ ] [Description of capability 2]
### Regression Evals
- [ ] [Existing behavior 1 still works]
- [ ] [Existing behavior 2 still works]
### Success Criteria
- pass@3 > 90% for capability evals
- pass^3 = 100% for regression evals
```
2. Prompt user to fill in specific criteria
## Check Evals
`/eval check feature-name`
Run evals for a feature:
1. Read eval definition from `.claude/evals/feature-name.md`
2. For each capability eval:
- Attempt to verify criterion
- Record PASS/FAIL
- Log attempt in `.claude/evals/feature-name.log`
3. For each regression eval:
- Run relevant tests
- Compare against baseline
- Record PASS/FAIL
4. Report current status:
```
EVAL CHECK: feature-name
========================
Capability: X/Y passing
Regression: X/Y passing
Status: IN PROGRESS / READY
```
## Report Evals
`/eval report feature-name`
Generate comprehensive eval report:
```
EVAL REPORT: feature-name
=========================
Generated: $(date)
CAPABILITY EVALS
----------------
[eval-1]: PASS (pass@1)
[eval-2]: PASS (pass@2) - required retry
[eval-3]: FAIL - see notes
REGRESSION EVALS
----------------
[test-1]: PASS
[test-2]: PASS
[test-3]: PASS
METRICS
-------
Capability pass@1: 67%
Capability pass@3: 100%
Regression pass^3: 100%
NOTES
-----
[Any issues, edge cases, or observations]
RECOMMENDATION
--------------
[SHIP / NEEDS WORK / BLOCKED]
```
## List Evals
`/eval list`
Show all eval definitions:
```
EVAL DEFINITIONS
================
feature-auth [3/5 passing] IN PROGRESS
feature-search [5/5 passing] READY
feature-export [0/4 passing] NOT STARTED
```
## Arguments
$ARGUMENTS:
- `define <name>` - Create new eval definition
- `check <name>` - Run and check evals
- `report <name>` - Generate full report
- `list` - Show all evals
- `clean` - Remove old eval logs (keeps last 10 runs)

178
.agent/knowledge/everything_claude/commands/evolve.md Normal file
View File

@@ -0,0 +1,178 @@
---
name: evolve
description: Analyze instincts and suggest or generate evolved structures
command: true
---
# Evolve Command
## Implementation
Run the instinct CLI using the plugin root path:
```bash
python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" evolve [--generate]
```
Or if `CLAUDE_PLUGIN_ROOT` is not set (manual installation):
```bash
python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py evolve [--generate]
```
Analyzes instincts and clusters related ones into higher-level structures:
- **Commands**: When instincts describe user-invoked actions
- **Skills**: When instincts describe auto-triggered behaviors
- **Agents**: When instincts describe complex, multi-step processes
## Usage
```
/evolve # Analyze all instincts and suggest evolutions
/evolve --generate # Also generate files under evolved/{skills,commands,agents}
```
## Evolution Rules
### → Command (User-Invoked)
When instincts describe actions a user would explicitly request:
- Multiple instincts about "when user asks to..."
- Instincts with triggers like "when creating a new X"
- Instincts that follow a repeatable sequence
Example:
- `new-table-step1`: "when adding a database table, create migration"
- `new-table-step2`: "when adding a database table, update schema"
- `new-table-step3`: "when adding a database table, regenerate types"
→ Creates: **new-table** command
### → Skill (Auto-Triggered)
When instincts describe behaviors that should happen automatically:
- Pattern-matching triggers
- Error handling responses
- Code style enforcement
Example:
- `prefer-functional`: "when writing functions, prefer functional style"
- `use-immutable`: "when modifying state, use immutable patterns"
- `avoid-classes`: "when designing modules, avoid class-based design"
→ Creates: `functional-patterns` skill
### → Agent (Needs Depth/Isolation)
When instincts describe complex, multi-step processes that benefit from isolation:
- Debugging workflows
- Refactoring sequences
- Research tasks
Example:
- `debug-step1`: "when debugging, first check logs"
- `debug-step2`: "when debugging, isolate the failing component"
- `debug-step3`: "when debugging, create minimal reproduction"
- `debug-step4`: "when debugging, verify fix with test"
→ Creates: **debugger** agent
## What to Do
1. Detect current project context
2. Read project + global instincts (project takes precedence on ID conflicts)
3. Group instincts by trigger/domain patterns
4. Identify:
- Skill candidates (trigger clusters with 2+ instincts)
- Command candidates (high-confidence workflow instincts)
- Agent candidates (larger, high-confidence clusters)
5. Show promotion candidates (project -> global) when applicable
6. If `--generate` is passed, write files to:
- Project scope: `~/.claude/homunculus/projects/<project-id>/evolved/`
- Global fallback: `~/.claude/homunculus/evolved/`
## Output Format
```
============================================================
EVOLVE ANALYSIS - 12 instincts
Project: my-app (a1b2c3d4e5f6)
Project-scoped: 8 | Global: 4
============================================================
High confidence instincts (>=80%): 5
## SKILL CANDIDATES
1. Cluster: "adding tests"
Instincts: 3
Avg confidence: 82%
Domains: testing
Scopes: project
## COMMAND CANDIDATES (2)
/adding-tests
From: test-first-workflow [project]
Confidence: 84%
## AGENT CANDIDATES (1)
adding-tests-agent
Covers 3 instincts
Avg confidence: 82%
```
## Flags
- `--generate`: Generate evolved files in addition to analysis output
## Generated File Format
### Command
```markdown
---
name: new-table
description: Create a new database table with migration, schema update, and type generation
command: /new-table
evolved_from:
- new-table-migration
- update-schema
- regenerate-types
---
# New Table Command
[Generated content based on clustered instincts]
## Steps
1. ...
2. ...
```
### Skill
```markdown
---
name: functional-patterns
description: Enforce functional programming patterns
evolved_from:
- prefer-functional
- use-immutable
- avoid-classes
---
# Functional Patterns Skill
[Generated content based on clustered instincts]
```
### Agent
```markdown
---
name: debugger
description: Systematic debugging agent
model: sonnet
evolved_from:
- debug-check-logs
- debug-isolate
- debug-reproduce
---
# Debugger Agent
[Generated content based on clustered instincts]
```

183
.agent/knowledge/everything_claude/commands/go-build.md Normal file
View File

@@ -0,0 +1,183 @@
---
description: Fix Go build errors, go vet warnings, and linter issues incrementally. Invokes the go-build-resolver agent for minimal, surgical fixes.
---
# Go Build and Fix
This command invokes the **go-build-resolver** agent to incrementally fix Go build errors with minimal changes.
## What This Command Does
1. **Run Diagnostics**: Execute `go build`, `go vet`, `staticcheck`
2. **Parse Errors**: Group by file and sort by severity
3. **Fix Incrementally**: One error at a time
4. **Verify Each Fix**: Re-run build after each change
5. **Report Summary**: Show what was fixed and what remains
## When to Use
Use `/go-build` when:
- `go build ./...` fails with errors
- `go vet ./...` reports issues
- `golangci-lint run` shows warnings
- Module dependencies are broken
- After pulling changes that break the build
## Diagnostic Commands Run
```bash
# Primary build check
go build ./...
# Static analysis
go vet ./...
# Extended linting (if available)
staticcheck ./...
golangci-lint run
# Module issues
go mod verify
go mod tidy -v
```
## Example Session
```text
User: /go-build
Agent:
# Go Build Resolution
## Initial Diagnostics
```bash
$ go build ./...
internal/service/user.go:25:15: undefined: UserRepository
internal/handler/api.go:42:9: cannot use x (type string) as type int
internal/handler/api.go:58:2: missing return at end of function
```
Errors found: 3
## Fix 1: Undefined Identifier
File: internal/service/user.go:25
Error: undefined: UserRepository
Cause: Missing import
```go
// Added import
import "project/internal/repository"
// Changed
var repo UserRepository
// To
var repo repository.UserRepository
```
```bash
$ go build ./...
# 2 errors remaining
```
## Fix 2: Type Mismatch
File: internal/handler/api.go:42
Error: cannot use x (type string) as type int
```go
// Changed
count := params.Get("count")
// To
countStr := params.Get("count")
count, _ := strconv.Atoi(countStr)
```
```bash
$ go build ./...
# 1 error remaining
```
## Fix 3: Missing Return
File: internal/handler/api.go:58
Error: missing return at end of function
```go
func GetUser(id string) (*User, error) {
if id == "" {
return nil, ErrInvalidID
}
user := findUser(id)
// Added missing return
return user, nil
}
```
```bash
$ go build ./...
# Build successful!
```
## Final Verification
```bash
$ go vet ./...
# No issues
$ go test ./...
ok project/internal/service 0.015s
ok project/internal/handler 0.023s
```
## Summary
| Metric | Count |
|--------|-------|
| Build errors fixed | 3 |
| Vet warnings fixed | 0 |
| Files modified | 2 |
| Remaining issues | 0 |
Build Status: ✅ SUCCESS
```
## Common Errors Fixed
| Error | Typical Fix |
|-------|-------------|
| `undefined: X` | Add import or fix typo |
| `cannot use X as Y` | Type conversion or fix assignment |
| `missing return` | Add return statement |
| `X does not implement Y` | Add missing method |
| `import cycle` | Restructure packages |
| `declared but not used` | Remove or use variable |
| `cannot find package` | `go get` or `go mod tidy` |
## Fix Strategy
1. **Build errors first** - Code must compile
2. **Vet warnings second** - Fix suspicious constructs
3. **Lint warnings third** - Style and best practices
4. **One fix at a time** - Verify each change
5. **Minimal changes** - Don't refactor, just fix
## Stop Conditions
The agent will stop and report if:
- Same error persists after 3 attempts
- Fix introduces more errors
- Requires architectural changes
- Missing external dependencies
## Related Commands
- `/go-test` - Run tests after build succeeds
- `/go-review` - Review code quality
- `/verify` - Full verification loop
## Related
- Agent: `agents/go-build-resolver.md`
- Skill: `skills/golang-patterns/`

148
.agent/knowledge/everything_claude/commands/go-review.md Normal file
View File

@@ -0,0 +1,148 @@
---
description: Comprehensive Go code review for idiomatic patterns, concurrency safety, error handling, and security. Invokes the go-reviewer agent.
---
# Go Code Review
This command invokes the **go-reviewer** agent for comprehensive Go-specific code review.
## What This Command Does
1. **Identify Go Changes**: Find modified `.go` files via `git diff`
2. **Run Static Analysis**: Execute `go vet`, `staticcheck`, and `golangci-lint`
3. **Security Scan**: Check for SQL injection, command injection, race conditions
4. **Concurrency Review**: Analyze goroutine safety, channel usage, mutex patterns
5. **Idiomatic Go Check**: Verify code follows Go conventions and best practices
6. **Generate Report**: Categorize issues by severity
## When to Use
Use `/go-review` when:
- After writing or modifying Go code
- Before committing Go changes
- Reviewing pull requests with Go code
- Onboarding to a new Go codebase
- Learning idiomatic Go patterns
## Review Categories
### CRITICAL (Must Fix)
- SQL/Command injection vulnerabilities
- Race conditions without synchronization
- Goroutine leaks
- Hardcoded credentials
- Unsafe pointer usage
- Ignored errors in critical paths
### HIGH (Should Fix)
- Missing error wrapping with context
- Panic instead of error returns
- Context not propagated
- Unbuffered channels causing deadlocks
- Interface not satisfied errors
- Missing mutex protection
### MEDIUM (Consider)
- Non-idiomatic code patterns
- Missing godoc comments on exports
- Inefficient string concatenation
- Slice not preallocated
- Table-driven tests not used
## Automated Checks Run
```bash
# Static analysis
go vet ./...
# Advanced checks (if installed)
staticcheck ./...
golangci-lint run
# Race detection
go build -race ./...
# Security vulnerabilities
govulncheck ./...
```
## Example Usage
```text
User: /go-review
Agent:
# Go Code Review Report
## Files Reviewed
- internal/handler/user.go (modified)
- internal/service/auth.go (modified)
## Static Analysis Results
✓ go vet: No issues
✓ staticcheck: No issues
## Issues Found
[CRITICAL] Race Condition
File: internal/service/auth.go:45
Issue: Shared map accessed without synchronization
```go
var cache = map[string]*Session{} // Concurrent access!
func GetSession(id string) *Session {
return cache[id] // Race condition
}
```
Fix: Use sync.RWMutex or sync.Map
```go
var (
cache = map[string]*Session{}
cacheMu sync.RWMutex
)
func GetSession(id string) *Session {
cacheMu.RLock()
defer cacheMu.RUnlock()
return cache[id]
}
```
[HIGH] Missing Error Context
File: internal/handler/user.go:28
Issue: Error returned without context
```go
return err // No context
```
Fix: Wrap with context
```go
return fmt.Errorf("get user %s: %w", userID, err)
```
## Summary
- CRITICAL: 1
- HIGH: 1
- MEDIUM: 0
Recommendation: ❌ Block merge until CRITICAL issue is fixed
```
## Approval Criteria
| Status | Condition |
|--------|-----------|
| ✅ Approve | No CRITICAL or HIGH issues |
| ⚠️ Warning | Only MEDIUM issues (merge with caution) |
| ❌ Block | CRITICAL or HIGH issues found |
## Integration with Other Commands
- Use `/go-test` first to ensure tests pass
- Use `/go-build` if build errors occur
- Use `/go-review` before committing
- Use `/code-review` for non-Go specific concerns
## Related
- Agent: `agents/go-reviewer.md`
- Skills: `skills/golang-patterns/`, `skills/golang-testing/`

268
.agent/knowledge/everything_claude/commands/go-test.md Normal file
View File

@@ -0,0 +1,268 @@
---
description: Enforce TDD workflow for Go. Write table-driven tests first, then implement. Verify 80%+ coverage with go test -cover.
---
# Go TDD Command
This command enforces test-driven development methodology for Go code using idiomatic Go testing patterns.
## What This Command Does
1. **Define Types/Interfaces**: Scaffold function signatures first
2. **Write Table-Driven Tests**: Create comprehensive test cases (RED)
3. **Run Tests**: Verify tests fail for the right reason
4. **Implement Code**: Write minimal code to pass (GREEN)
5. **Refactor**: Improve while keeping tests green
6. **Check Coverage**: Ensure 80%+ coverage
## When to Use
Use `/go-test` when:
- Implementing new Go functions
- Adding test coverage to existing code
- Fixing bugs (write failing test first)
- Building critical business logic
- Learning TDD workflow in Go
## TDD Cycle
```
RED → Write failing table-driven test
GREEN → Implement minimal code to pass
REFACTOR → Improve code, tests stay green
REPEAT → Next test case
```
## Example Session
````
User: /go-test I need a function to validate email addresses
Agent:
# TDD Session: Email Validator
## Step 1: Define Interface
```go
// validator/email.go
package validator
// ValidateEmail checks if the given string is a valid email address.
// Returns nil if valid, error describing the issue otherwise.
func ValidateEmail(email string) error {
panic("not implemented")
}
```
## Step 2: Write Table-Driven Tests (RED)
```go
// validator/email_test.go
package validator
import (
"testing"
)
func TestValidateEmail(t *testing.T) {
tests := []struct {
name string
email string
wantErr bool
}{
// Valid emails
{"simple email", "user@example.com", false},
{"with subdomain", "user@mail.example.com", false},
{"with plus", "user+tag@example.com", false},
{"with dots", "first.last@example.com", false},
// Invalid emails
{"empty string", "", true},
{"no at sign", "userexample.com", true},
{"no domain", "user@", true},
{"no local part", "@example.com", true},
{"double at", "user@@example.com", true},
{"spaces", "user @example.com", true},
{"no tld", "user@example", true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
err := ValidateEmail(tt.email)
if tt.wantErr && err == nil {
t.Errorf("ValidateEmail(%q) = nil; want error", tt.email)
}
if !tt.wantErr && err != nil {
t.Errorf("ValidateEmail(%q) = %v; want nil", tt.email, err)
}
})
}
}
```
## Step 3: Run Tests - Verify FAIL
```bash
$ go test ./validator/...
--- FAIL: TestValidateEmail (0.00s)
--- FAIL: TestValidateEmail/simple_email (0.00s)
panic: not implemented
FAIL
```
✓ Tests fail as expected (panic).
## Step 4: Implement Minimal Code (GREEN)
```go
// validator/email.go
package validator
import (
"errors"
"regexp"
)
var emailRegex = regexp.MustCompile(`^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`)
var (
ErrEmailEmpty = errors.New("email cannot be empty")
ErrEmailInvalid = errors.New("email format is invalid")
)
func ValidateEmail(email string) error {
if email == "" {
return ErrEmailEmpty
}
if !emailRegex.MatchString(email) {
return ErrEmailInvalid
}
return nil
}
```
## Step 5: Run Tests - Verify PASS
```bash
$ go test ./validator/...
PASS
ok project/validator 0.003s
```
✓ All tests passing!
## Step 6: Check Coverage
```bash
$ go test -cover ./validator/...
PASS
coverage: 100.0% of statements
ok project/validator 0.003s
```
✓ Coverage: 100%
## TDD Complete!
````
## Test Patterns
### Table-Driven Tests
```go
tests := []struct {
name string
input InputType
want OutputType
wantErr bool
}{
{"case 1", input1, want1, false},
{"case 2", input2, want2, true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
got, err := Function(tt.input)
// assertions
})
}
```
### Parallel Tests
```go
for _, tt := range tests {
tt := tt // Capture
t.Run(tt.name, func(t *testing.T) {
t.Parallel()
// test body
})
}
```
### Test Helpers
```go
func setupTestDB(t *testing.T) *sql.DB {
t.Helper()
db := createDB()
t.Cleanup(func() { db.Close() })
return db
}
```
## Coverage Commands
```bash
# Basic coverage
go test -cover ./...
# Coverage profile
go test -coverprofile=coverage.out ./...
# View in browser
go tool cover -html=coverage.out
# Coverage by function
go tool cover -func=coverage.out
# With race detection
go test -race -cover ./...
```
## Coverage Targets
| Code Type | Target |
|-----------|--------|
| Critical business logic | 100% |
| Public APIs | 90%+ |
| General code | 80%+ |
| Generated code | Exclude |
## TDD Best Practices
**DO:**
- Write test FIRST, before any implementation
- Run tests after each change
- Use table-driven tests for comprehensive coverage
- Test behavior, not implementation details
- Include edge cases (empty, nil, max values)
**DON'T:**
- Write implementation before tests
- Skip the RED phase
- Test private functions directly
- Use `time.Sleep` in tests
- Ignore flaky tests
## Related Commands
- `/go-build` - Fix build errors
- `/go-review` - Review code after implementation
- `/verify` - Run full verification loop
## Related
- Skill: `skills/golang-testing/`
- Skill: `skills/tdd-workflow/`

70
.agent/knowledge/everything_claude/commands/gradle-build.md Normal file
View File

@@ -0,0 +1,70 @@
---
description: Fix Gradle build errors for Android and KMP projects
---
# Gradle Build Fix
Incrementally fix Gradle build and compilation errors for Android and Kotlin Multiplatform projects.
## Step 1: Detect Build Configuration
Identify the project type and run the appropriate build:
| Indicator | Build Command |
|-----------|---------------|
| `build.gradle.kts` + `composeApp/` (KMP) | `./gradlew composeApp:compileKotlinMetadata 2>&1` |
| `build.gradle.kts` + `app/` (Android) | `./gradlew app:compileDebugKotlin 2>&1` |
| `settings.gradle.kts` with modules | `./gradlew assemble 2>&1` |
| Detekt configured | `./gradlew detekt 2>&1` |
Also check `gradle.properties` and `local.properties` for configuration.
## Step 2: Parse and Group Errors
1. Run the build command and capture output
2. Separate Kotlin compilation errors from Gradle configuration errors
3. Group by module and file path
4. Sort: configuration errors first, then compilation errors by dependency order
## Step 3: Fix Loop
For each error:
1. **Read the file** — Full context around the error line
2. **Diagnose** — Common categories:
- Missing import or unresolved reference
- Type mismatch or incompatible types
- Missing dependency in `build.gradle.kts`
- Expect/actual mismatch (KMP)
- Compose compiler error
3. **Fix minimally** — Smallest change that resolves the error
4. **Re-run build** — Verify fix and check for new errors
5. **Continue** — Move to next error
## Step 4: Guardrails
Stop and ask the user if:
- Fix introduces more errors than it resolves
- Same error persists after 3 attempts
- Error requires adding new dependencies or changing module structure
- Gradle sync itself fails (configuration-phase error)
- Error is in generated code (Room, SQLDelight, KSP)
## Step 5: Summary
Report:
- Errors fixed (module, file, description)
- Errors remaining
- New errors introduced (should be zero)
- Suggested next steps
## Common Gradle/KMP Fixes
| Error | Fix |
|-------|-----|
| Unresolved reference in `commonMain` | Check if the dependency is in `commonMain.dependencies {}` |
| Expect declaration without actual | Add `actual` implementation in each platform source set |
| Compose compiler version mismatch | Align Kotlin and Compose compiler versions in `libs.versions.toml` |
| Duplicate class | Check for conflicting dependencies with `./gradlew dependencies` |
| KSP error | Run `./gradlew kspCommonMainKotlinMetadata` to regenerate |
| Configuration cache issue | Check for non-serializable task inputs |

71
.agent/knowledge/everything_claude/commands/harness-audit.md Normal file
View File

@@ -0,0 +1,71 @@
# Harness Audit Command
Run a deterministic repository harness audit and return a prioritized scorecard.
## Usage
`/harness-audit [scope] [--format text|json]`
- `scope` (optional): `repo` (default), `hooks`, `skills`, `commands`, `agents`
- `--format`: output style (`text` default, `json` for automation)
## Deterministic Engine
Always run:
```bash
node scripts/harness-audit.js <scope> --format <text|json>
```
This script is the source of truth for scoring and checks. Do not invent additional dimensions or ad-hoc points.
Rubric version: `2026-03-16`.
The script computes 7 fixed categories (`0-10` normalized each):
1. Tool Coverage
2. Context Efficiency
3. Quality Gates
4. Memory Persistence
5. Eval Coverage
6. Security Guardrails
7. Cost Efficiency
Scores are derived from explicit file/rule checks and are reproducible for the same commit.
## Output Contract
Return:
1. `overall_score` out of `max_score` (70 for `repo`; smaller for scoped audits)
2. Category scores and concrete findings
3. Failed checks with exact file paths
4. Top 3 actions from the deterministic output (`top_actions`)
5. Suggested ECC skills to apply next
## Checklist
- Use script output directly; do not rescore manually.
- If `--format json` is requested, return the script JSON unchanged.
- If text is requested, summarize failing checks and top actions.
- Include exact file paths from `checks[]` and `top_actions[]`.
## Example Result
```text
Harness Audit (repo): 66/70
- Tool Coverage: 10/10 (10/10 pts)
- Context Efficiency: 9/10 (9/10 pts)
- Quality Gates: 10/10 (10/10 pts)
Top 3 Actions:
1) [Security Guardrails] Add prompt/tool preflight security guards in hooks/hooks.json. (hooks/hooks.json)
2) [Tool Coverage] Sync commands/harness-audit.md and .opencode/commands/harness-audit.md. (.opencode/commands/harness-audit.md)
3) [Eval Coverage] Increase automated test coverage across scripts/hooks/lib. (tests/)
```
## Arguments
$ARGUMENTS:
- `repo|hooks|skills|commands|agents` (optional scope)
- `--format text|json` (optional output format)

66
.agent/knowledge/everything_claude/commands/instinct-export.md Normal file
View File

@@ -0,0 +1,66 @@
---
name: instinct-export
description: Export instincts from project/global scope to a file
command: /instinct-export
---
# Instinct Export Command
Exports instincts to a shareable format. Perfect for:
- Sharing with teammates
- Transferring to a new machine
- Contributing to project conventions
## Usage
```
/instinct-export # Export all personal instincts
/instinct-export --domain testing # Export only testing instincts
/instinct-export --min-confidence 0.7 # Only export high-confidence instincts
/instinct-export --output team-instincts.yaml
/instinct-export --scope project --output project-instincts.yaml
```
## What to Do
1. Detect current project context
2. Load instincts by selected scope:
- `project`: current project only
- `global`: global only
- `all`: project + global merged (default)
3. Apply filters (`--domain`, `--min-confidence`)
4. Write YAML-style export to file (or stdout if no output path provided)
## Output Format
Creates a YAML file:
```yaml
# Instincts Export
# Generated: 2025-01-22
# Source: personal
# Count: 12 instincts
---
id: prefer-functional-style
trigger: "when writing new functions"
confidence: 0.8
domain: code-style
source: session-observation
scope: project
project_id: a1b2c3d4e5f6
project_name: my-app
---
# Prefer Functional Style
## Action
Use functional patterns over classes.
```
## Flags
- `--domain <name>`: Export only specified domain
- `--min-confidence <n>`: Minimum confidence threshold
- `--output <file>`: Output file path (prints to stdout when omitted)
- `--scope <project|global|all>`: Export scope (default: `all`)

114
.agent/knowledge/everything_claude/commands/instinct-import.md Normal file
View File

@@ -0,0 +1,114 @@
---
name: instinct-import
description: Import instincts from file or URL into project/global scope
command: true
---
# Instinct Import Command
## Implementation
Run the instinct CLI using the plugin root path:
```bash
python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" import <file-or-url> [--dry-run] [--force] [--min-confidence 0.7] [--scope project|global]
```
Or if `CLAUDE_PLUGIN_ROOT` is not set (manual installation):
```bash
python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py import <file-or-url>
```
Import instincts from local file paths or HTTP(S) URLs.
## Usage
```
/instinct-import team-instincts.yaml
/instinct-import https://github.com/org/repo/instincts.yaml
/instinct-import team-instincts.yaml --dry-run
/instinct-import team-instincts.yaml --scope global --force
```
## What to Do
1. Fetch the instinct file (local path or URL)
2. Parse and validate the format
3. Check for duplicates with existing instincts
4. Merge or add new instincts
5. Save to inherited instincts directory:
- Project scope: `~/.claude/homunculus/projects/<project-id>/instincts/inherited/`
- Global scope: `~/.claude/homunculus/instincts/inherited/`
## Import Process
```
📥 Importing instincts from: team-instincts.yaml
================================================
Found 12 instincts to import.
Analyzing conflicts...
## New Instincts (8)
These will be added:
✓ use-zod-validation (confidence: 0.7)
✓ prefer-named-exports (confidence: 0.65)
✓ test-async-functions (confidence: 0.8)
...
## Duplicate Instincts (3)
Already have similar instincts:
⚠️ prefer-functional-style
Local: 0.8 confidence, 12 observations
Import: 0.7 confidence
→ Keep local (higher confidence)
⚠️ test-first-workflow
Local: 0.75 confidence
Import: 0.9 confidence
→ Update to import (higher confidence)
Import 8 new, update 1?
```
## Merge Behavior
When importing an instinct with an existing ID:
- Higher-confidence import becomes an update candidate
- Equal/lower-confidence import is skipped
- User confirms unless `--force` is used
## Source Tracking
Imported instincts are marked with:
```yaml
source: inherited
scope: project
imported_from: "team-instincts.yaml"
project_id: "a1b2c3d4e5f6"
project_name: "my-project"
```
## Flags
- `--dry-run`: Preview without importing
- `--force`: Skip confirmation prompt
- `--min-confidence <n>`: Only import instincts above threshold
- `--scope <project|global>`: Select target scope (default: `project`)
## Output
After import:
```
✅ Import complete!
Added: 8 instincts
Updated: 1 instinct
Skipped: 3 instincts (equal/higher confidence already exists)
New instincts saved to: ~/.claude/homunculus/instincts/inherited/
Run /instinct-status to see all instincts.
```

59
.agent/knowledge/everything_claude/commands/instinct-status.md Normal file
View File

@@ -0,0 +1,59 @@
---
name: instinct-status
description: Show learned instincts (project + global) with confidence
command: true
---
# Instinct Status Command
Shows learned instincts for the current project plus global instincts, grouped by domain.
## Implementation
Run the instinct CLI using the plugin root path:
```bash
python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" status
```
Or if `CLAUDE_PLUGIN_ROOT` is not set (manual installation), use:
```bash
python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py status
```
## Usage
```
/instinct-status
```
## What to Do
1. Detect current project context (git remote/path hash)
2. Read project instincts from `~/.claude/homunculus/projects/<project-id>/instincts/`
3. Read global instincts from `~/.claude/homunculus/instincts/`
4. Merge with precedence rules (project overrides global when IDs collide)
5. Display grouped by domain with confidence bars and observation stats
## Output Format
```
============================================================
INSTINCT STATUS - 12 total
============================================================
Project: my-app (a1b2c3d4e5f6)
Project instincts: 8
Global instincts: 4
## PROJECT-SCOPED (my-app)
### WORKFLOW (3)
███████░░░ 70% grep-before-edit [project]
trigger: when modifying code
## GLOBAL (apply to all projects)
### SECURITY (2)
█████████░ 85% validate-user-input [global]
trigger: when handling user input
```

174
.agent/knowledge/everything_claude/commands/kotlin-build.md Normal file
View File

@@ -0,0 +1,174 @@
---
description: Fix Kotlin/Gradle build errors, compiler warnings, and dependency issues incrementally. Invokes the kotlin-build-resolver agent for minimal, surgical fixes.
---
# Kotlin Build and Fix
This command invokes the **kotlin-build-resolver** agent to incrementally fix Kotlin build errors with minimal changes.
## What This Command Does
1. **Run Diagnostics**: Execute `./gradlew build`, `detekt`, `ktlintCheck`
2. **Parse Errors**: Group by file and sort by severity
3. **Fix Incrementally**: One error at a time
4. **Verify Each Fix**: Re-run build after each change
5. **Report Summary**: Show what was fixed and what remains
## When to Use
Use `/kotlin-build` when:
- `./gradlew build` fails with errors
- Kotlin compiler reports errors
- `./gradlew detekt` reports violations
- Gradle dependency resolution fails
- After pulling changes that break the build
## Diagnostic Commands Run
```bash
# Primary build check
./gradlew build 2>&1
# Static analysis
./gradlew detekt 2>&1 || echo "detekt not configured"
./gradlew ktlintCheck 2>&1 || echo "ktlint not configured"
# Dependency issues
./gradlew dependencies --configuration runtimeClasspath 2>&1 | head -100
# Optional deep refresh when caches or dependency metadata are suspect
./gradlew build --refresh-dependencies
```
## Example Session
````text
User: /kotlin-build
Agent:
# Kotlin Build Resolution
## Initial Diagnostics
```bash
$ ./gradlew build
e: src/main/kotlin/com/example/service/UserService.kt:25:15 Unresolved reference: UserRepository
e: src/main/kotlin/com/example/routes/UserRoutes.kt:42:9 Type mismatch: inferred type is String but Int was expected
e: src/main/kotlin/com/example/routes/UserRoutes.kt:58:5 'when' expression must be exhaustive
```
Errors found: 3
## Fix 1: Unresolved Reference
File: src/main/kotlin/com/example/service/UserService.kt:25
Error: Unresolved reference: UserRepository
Cause: Missing import
```kotlin
// Added import
import com.example.repository.UserRepository
```
```bash
$ ./gradlew build
# 2 errors remaining
```
## Fix 2: Type Mismatch
File: src/main/kotlin/com/example/routes/UserRoutes.kt:42
Error: Type mismatch: inferred type is String but Int was expected
```kotlin
// Changed
val count = call.parameters["count"]
// To
val count = call.parameters["count"]?.toIntOrNull()
?: return@get call.respond(HttpStatusCode.BadRequest, "Invalid count")
```
```bash
$ ./gradlew build
# 1 error remaining
```
## Fix 3: Non-Exhaustive When
File: src/main/kotlin/com/example/routes/UserRoutes.kt:58
Error: 'when' expression must be exhaustive
```kotlin
// Added missing branch
when (user.role) {
Role.ADMIN -> handleAdmin(user)
Role.USER -> handleUser(user)
Role.MODERATOR -> handleModerator(user) // Added
}
```
```bash
$ ./gradlew build
# Build successful!
```
## Final Verification
```bash
$ ./gradlew detekt
# No issues
$ ./gradlew test
# All tests passed
```
## Summary
| Metric | Count |
|--------|-------|
| Build errors fixed | 3 |
| Detekt issues fixed | 0 |
| Files modified | 2 |
| Remaining issues | 0 |
Build Status: ✅ SUCCESS
````
## Common Errors Fixed
| Error | Typical Fix |
|-------|-------------|
| `Unresolved reference: X` | Add import or dependency |
| `Type mismatch` | Fix type conversion or assignment |
| `'when' must be exhaustive` | Add missing sealed class branches |
| `Suspend function can only be called from coroutine` | Add `suspend` modifier |
| `Smart cast impossible` | Use local `val` or `let` |
| `None of the following candidates is applicable` | Fix argument types |
| `Could not resolve dependency` | Fix version or add repository |
## Fix Strategy
1. **Build errors first** - Code must compile
2. **Detekt violations second** - Fix code quality issues
3. **ktlint warnings third** - Fix formatting
4. **One fix at a time** - Verify each change
5. **Minimal changes** - Don't refactor, just fix
## Stop Conditions
The agent will stop and report if:
- Same error persists after 3 attempts
- Fix introduces more errors
- Requires architectural changes
- Missing external dependencies
## Related Commands
- `/kotlin-test` - Run tests after build succeeds
- `/kotlin-review` - Review code quality
- `/verify` - Full verification loop
## Related
- Agent: `agents/kotlin-build-resolver.md`
- Skill: `skills/kotlin-patterns/`

140
.agent/knowledge/everything_claude/commands/kotlin-review.md Normal file
View File

@@ -0,0 +1,140 @@
---
description: Comprehensive Kotlin code review for idiomatic patterns, null safety, coroutine safety, and security. Invokes the kotlin-reviewer agent.
---
# Kotlin Code Review
This command invokes the **kotlin-reviewer** agent for comprehensive Kotlin-specific code review.
## What This Command Does
1. **Identify Kotlin Changes**: Find modified `.kt` and `.kts` files via `git diff`
2. **Run Build & Static Analysis**: Execute `./gradlew build`, `detekt`, `ktlintCheck`
3. **Security Scan**: Check for SQL injection, command injection, hardcoded secrets
4. **Null Safety Review**: Analyze `!!` usage, platform type handling, unsafe casts
5. **Coroutine Review**: Check structured concurrency, dispatcher usage, cancellation
6. **Generate Report**: Categorize issues by severity
## When to Use
Use `/kotlin-review` when:
- After writing or modifying Kotlin code
- Before committing Kotlin changes
- Reviewing pull requests with Kotlin code
- Onboarding to a new Kotlin codebase
- Learning idiomatic Kotlin patterns
## Review Categories
### CRITICAL (Must Fix)
- SQL/Command injection vulnerabilities
- Force-unwrap `!!` without justification
- Platform type null safety violations
- GlobalScope usage (structured concurrency violation)
- Hardcoded credentials
- Unsafe deserialization
### HIGH (Should Fix)
- Mutable state where immutable suffices
- Blocking calls inside coroutine context
- Missing cancellation checks in long loops
- Non-exhaustive `when` on sealed types
- Large functions (>50 lines)
- Deep nesting (>4 levels)
### MEDIUM (Consider)
- Non-idiomatic Kotlin (Java-style patterns)
- Missing trailing commas
- Scope function misuse or nesting
- Missing sequence for large collection chains
- Redundant explicit types
## Automated Checks Run
```bash
# Build check
./gradlew build
# Static analysis
./gradlew detekt
# Formatting check
./gradlew ktlintCheck
# Tests
./gradlew test
```
## Example Usage
````text
User: /kotlin-review
Agent:
# Kotlin Code Review Report
## Files Reviewed
- src/main/kotlin/com/example/service/UserService.kt (modified)
- src/main/kotlin/com/example/routes/UserRoutes.kt (modified)
## Static Analysis Results
✓ Build: Successful
✓ detekt: No issues
⚠ ktlint: 2 formatting warnings
## Issues Found
[CRITICAL] Force-Unwrap Null Safety
File: src/main/kotlin/com/example/service/UserService.kt:28
Issue: Using !! on nullable repository result
```kotlin
val user = repository.findById(id)!! // NPE risk
```
Fix: Use safe call with error handling
```kotlin
val user = repository.findById(id)
?: throw UserNotFoundException("User $id not found")
```
[HIGH] GlobalScope Usage
File: src/main/kotlin/com/example/routes/UserRoutes.kt:45
Issue: Using GlobalScope breaks structured concurrency
```kotlin
GlobalScope.launch {
notificationService.sendWelcome(user)
}
```
Fix: Use the call's coroutine scope
```kotlin
launch {
notificationService.sendWelcome(user)
}
```
## Summary
- CRITICAL: 1
- HIGH: 1
- MEDIUM: 0
Recommendation: ❌ Block merge until CRITICAL issue is fixed
````
## Approval Criteria
| Status | Condition |
|--------|-----------|
| ✅ Approve | No CRITICAL or HIGH issues |
| ⚠️ Warning | Only MEDIUM issues (merge with caution) |
| ❌ Block | CRITICAL or HIGH issues found |
## Integration with Other Commands
- Use `/kotlin-test` first to ensure tests pass
- Use `/kotlin-build` if build errors occur
- Use `/kotlin-review` before committing
- Use `/code-review` for non-Kotlin-specific concerns
## Related
- Agent: `agents/kotlin-reviewer.md`
- Skills: `skills/kotlin-patterns/`, `skills/kotlin-testing/`

312
.agent/knowledge/everything_claude/commands/kotlin-test.md Normal file
View File

@@ -0,0 +1,312 @@
---
description: Enforce TDD workflow for Kotlin. Write Kotest tests first, then implement. Verify 80%+ coverage with Kover.
---
# Kotlin TDD Command
This command enforces test-driven development methodology for Kotlin code using Kotest, MockK, and Kover.
## What This Command Does
1. **Define Types/Interfaces**: Scaffold function signatures first
2. **Write Kotest Tests**: Create comprehensive test specs (RED)
3. **Run Tests**: Verify tests fail for the right reason
4. **Implement Code**: Write minimal code to pass (GREEN)
5. **Refactor**: Improve while keeping tests green
6. **Check Coverage**: Ensure 80%+ coverage with Kover
## When to Use
Use `/kotlin-test` when:
- Implementing new Kotlin functions or classes
- Adding test coverage to existing Kotlin code
- Fixing bugs (write failing test first)
- Building critical business logic
- Learning TDD workflow in Kotlin
## TDD Cycle
```
RED -> Write failing Kotest test
GREEN -> Implement minimal code to pass
REFACTOR -> Improve code, tests stay green
REPEAT -> Next test case
```
## Example Session
````text
User: /kotlin-test I need a function to validate user registration requests
Agent:
# TDD Session: Registration Validator
## Step 1: Define Interface
```kotlin
// validator/RegistrationValidator.kt
package com.example.validator
data class RegistrationRequest(
val name: String,
val email: String,
val password: String,
)
sealed class ValidationResult {
data object Valid : ValidationResult()
data class Invalid(val errors: List<String>) : ValidationResult()
}
fun validateRegistration(request: RegistrationRequest): ValidationResult {
TODO("not implemented")
}
```
## Step 2: Write Kotest Tests (RED)
```kotlin
// validator/RegistrationValidatorTest.kt
package com.example.validator
import io.kotest.core.spec.style.FunSpec
import io.kotest.matchers.shouldBe
import io.kotest.matchers.types.shouldBeInstanceOf
class RegistrationValidatorTest : FunSpec({
test("valid registration returns Valid") {
val request = RegistrationRequest(
name = "Alice",
email = "alice@example.com",
password = "SecureP@ss1",
)
val result = validateRegistration(request)
result.shouldBeInstanceOf<ValidationResult.Valid>()
}
test("blank name returns Invalid") {
val request = RegistrationRequest(
name = "",
email = "alice@example.com",
password = "SecureP@ss1",
)
val result = validateRegistration(request)
val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
invalid.errors shouldBe listOf("Name is required")
}
test("invalid email returns Invalid") {
val request = RegistrationRequest(
name = "Alice",
email = "not-an-email",
password = "SecureP@ss1",
)
val result = validateRegistration(request)
val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
invalid.errors shouldBe listOf("Invalid email format")
}
test("short password returns Invalid") {
val request = RegistrationRequest(
name = "Alice",
email = "alice@example.com",
password = "short",
)
val result = validateRegistration(request)
val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
invalid.errors shouldBe listOf("Password must be at least 8 characters")
}
test("multiple errors returns all errors") {
val request = RegistrationRequest(
name = "",
email = "bad",
password = "short",
)
val result = validateRegistration(request)
val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
invalid.errors.size shouldBe 3
}
})
```
## Step 3: Run Tests - Verify FAIL
```bash
$ ./gradlew test
RegistrationValidatorTest > valid registration returns Valid FAILED
kotlin.NotImplementedError: An operation is not implemented
FAILED (5 tests, 0 passed, 5 failed)
```
✓ Tests fail as expected (NotImplementedError).
## Step 4: Implement Minimal Code (GREEN)
```kotlin
// validator/RegistrationValidator.kt
package com.example.validator
private val EMAIL_REGEX = Regex("^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$")
private const val MIN_PASSWORD_LENGTH = 8
fun validateRegistration(request: RegistrationRequest): ValidationResult {
val errors = buildList {
if (request.name.isBlank()) add("Name is required")
if (!EMAIL_REGEX.matches(request.email)) add("Invalid email format")
if (request.password.length < MIN_PASSWORD_LENGTH) add("Password must be at least $MIN_PASSWORD_LENGTH characters")
}
return if (errors.isEmpty()) ValidationResult.Valid
else ValidationResult.Invalid(errors)
}
```
## Step 5: Run Tests - Verify PASS
```bash
$ ./gradlew test
RegistrationValidatorTest > valid registration returns Valid PASSED
RegistrationValidatorTest > blank name returns Invalid PASSED
RegistrationValidatorTest > invalid email returns Invalid PASSED
RegistrationValidatorTest > short password returns Invalid PASSED
RegistrationValidatorTest > multiple errors returns all errors PASSED
PASSED (5 tests, 5 passed, 0 failed)
```
✓ All tests passing!
## Step 6: Check Coverage
```bash
$ ./gradlew koverHtmlReport
Coverage: 100.0% of statements
```
✓ Coverage: 100%
## TDD Complete!
````
## Test Patterns
### StringSpec (Simplest)
```kotlin
class CalculatorTest : StringSpec({
"add two positive numbers" {
Calculator.add(2, 3) shouldBe 5
}
})
```
### BehaviorSpec (BDD)
```kotlin
class OrderServiceTest : BehaviorSpec({
Given("a valid order") {
When("placed") {
Then("should be confirmed") { /* ... */ }
}
}
})
```
### Data-Driven Tests
```kotlin
class ParserTest : FunSpec({
context("valid inputs") {
withData("2026-01-15", "2026-12-31", "2000-01-01") { input ->
parseDate(input).shouldNotBeNull()
}
}
})
```
### Coroutine Testing
```kotlin
class AsyncServiceTest : FunSpec({
test("concurrent fetch completes") {
runTest {
val result = service.fetchAll()
result.shouldNotBeEmpty()
}
}
})
```
## Coverage Commands
```bash
# Run tests with coverage
./gradlew koverHtmlReport
# Verify coverage thresholds
./gradlew koverVerify
# XML report for CI
./gradlew koverXmlReport
# Open HTML report
open build/reports/kover/html/index.html
# Run specific test class
./gradlew test --tests "com.example.UserServiceTest"
# Run with verbose output
./gradlew test --info
```
## Coverage Targets
| Code Type | Target |
|-----------|--------|
| Critical business logic | 100% |
| Public APIs | 90%+ |
| General code | 80%+ |
| Generated code | Exclude |
## TDD Best Practices
**DO:**
- Write test FIRST, before any implementation
- Run tests after each change
- Use Kotest matchers for expressive assertions
- Use MockK's `coEvery`/`coVerify` for suspend functions
- Test behavior, not implementation details
- Include edge cases (empty, null, max values)
**DON'T:**
- Write implementation before tests
- Skip the RED phase
- Test private functions directly
- Use `Thread.sleep()` in coroutine tests
- Ignore flaky tests
## Related Commands
- `/kotlin-build` - Fix build errors
- `/kotlin-review` - Review code after implementation
- `/verify` - Run full verification loop
## Related
- Skill: `skills/kotlin-testing/`
- Skill: `skills/tdd-workflow/`

116
.agent/knowledge/everything_claude/commands/learn-eval.md Normal file
View File

@@ -0,0 +1,116 @@
---
description: "Extract reusable patterns from the session, self-evaluate quality before saving, and determine the right save location (Global vs Project)."
---
# /learn-eval - Extract, Evaluate, then Save
Extends `/learn` with a quality gate, save-location decision, and knowledge-placement awareness before writing any skill file.
## What to Extract
Look for:
1. **Error Resolution Patterns** — root cause + fix + reusability
2. **Debugging Techniques** — non-obvious steps, tool combinations
3. **Workarounds** — library quirks, API limitations, version-specific fixes
4. **Project-Specific Patterns** — conventions, architecture decisions, integration patterns
## Process
1. Review the session for extractable patterns
2. Identify the most valuable/reusable insight
3. **Determine save location:**
- Ask: "Would this pattern be useful in a different project?"
- **Global** (`~/.claude/skills/learned/`): Generic patterns usable across 2+ projects (bash compatibility, LLM API behavior, debugging techniques, etc.)
- **Project** (`.claude/skills/learned/` in current project): Project-specific knowledge (quirks of a particular config file, project-specific architecture decisions, etc.)
- When in doubt, choose Global (moving Global → Project is easier than the reverse)
4. Draft the skill file using this format:
```markdown
---
name: pattern-name
description: "Under 130 characters"
user-invocable: false
origin: auto-extracted
---
# [Descriptive Pattern Name]
**Extracted:** [Date]
**Context:** [Brief description of when this applies]
## Problem
[What problem this solves - be specific]
## Solution
[The pattern/technique/workaround - with code examples]
## When to Use
[Trigger conditions]
```
5. **Quality gate — Checklist + Holistic verdict**
### 5a. Required checklist (verify by actually reading files)
Execute **all** of the following before evaluating the draft:
- [ ] Grep `~/.claude/skills/` and relevant project `.claude/skills/` files by keyword to check for content overlap
- [ ] Check MEMORY.md (both project and global) for overlap
- [ ] Consider whether appending to an existing skill would suffice
- [ ] Confirm this is a reusable pattern, not a one-off fix
### 5b. Holistic verdict
Synthesize the checklist results and draft quality, then choose **one** of the following:
| Verdict | Meaning | Next Action |
|---------|---------|-------------|
| **Save** | Unique, specific, well-scoped | Proceed to Step 6 |
| **Improve then Save** | Valuable but needs refinement | List improvements → revise → re-evaluate (once) |
| **Absorb into [X]** | Should be appended to an existing skill | Show target skill and additions → Step 6 |
| **Drop** | Trivial, redundant, or too abstract | Explain reasoning and stop |
**Guideline dimensions** (informing the verdict, not scored):
- **Specificity & Actionability**: Contains code examples or commands that are immediately usable
- **Scope Fit**: Name, trigger conditions, and content are aligned and focused on a single pattern
- **Uniqueness**: Provides value not covered by existing skills (informed by checklist results)
- **Reusability**: Realistic trigger scenarios exist in future sessions
6. **Verdict-specific confirmation flow**
- **Improve then Save**: Present the required improvements + revised draft + updated checklist/verdict after one re-evaluation; if the revised verdict is **Save**, save after user confirmation, otherwise follow the new verdict
- **Save**: Present save path + checklist results + 1-line verdict rationale + full draft → save after user confirmation
- **Absorb into [X]**: Present target path + additions (diff format) + checklist results + verdict rationale → append after user confirmation
- **Drop**: Show checklist results + reasoning only (no confirmation needed)
7. Save / Absorb to the determined location
## Output Format for Step 5
```
### Checklist
- [x] skills/ grep: no overlap (or: overlap found → details)
- [x] MEMORY.md: no overlap (or: overlap found → details)
- [x] Existing skill append: new file appropriate (or: should append to [X])
- [x] Reusability: confirmed (or: one-off → Drop)
### Verdict: Save / Improve then Save / Absorb into [X] / Drop
**Rationale:** (1-2 sentences explaining the verdict)
```
## Design Rationale
This version replaces the previous 5-dimension numeric scoring rubric (Specificity, Actionability, Scope Fit, Non-redundancy, Coverage scored 1-5) with a checklist-based holistic verdict system. Modern frontier models (Opus 4.6+) have strong contextual judgment — forcing rich qualitative signals into numeric scores loses nuance and can produce misleading totals. The holistic approach lets the model weigh all factors naturally, producing more accurate save/drop decisions while the explicit checklist ensures no critical check is skipped.
## Notes
- Don't extract trivial fixes (typos, simple syntax errors)
- Don't extract one-time issues (specific API outages, etc.)
- Focus on patterns that will save time in future sessions
- Keep skills focused — one pattern per skill
- When the verdict is Absorb, append to the existing skill rather than creating a new file

70
.agent/knowledge/everything_claude/commands/learn.md Normal file
View File

@@ -0,0 +1,70 @@
# /learn - Extract Reusable Patterns
Analyze the current session and extract any patterns worth saving as skills.
## Trigger
Run `/learn` at any point during a session when you've solved a non-trivial problem.
## What to Extract
Look for:
1. **Error Resolution Patterns**
- What error occurred?
- What was the root cause?
- What fixed it?
- Is this reusable for similar errors?
2. **Debugging Techniques**
- Non-obvious debugging steps
- Tool combinations that worked
- Diagnostic patterns
3. **Workarounds**
- Library quirks
- API limitations
- Version-specific fixes
4. **Project-Specific Patterns**
- Codebase conventions discovered
- Architecture decisions made
- Integration patterns
## Output Format
Create a skill file at `~/.claude/skills/learned/[pattern-name].md`:
```markdown
# [Descriptive Pattern Name]
**Extracted:** [Date]
**Context:** [Brief description of when this applies]
## Problem
[What problem this solves - be specific]
## Solution
[The pattern/technique/workaround]
## Example
[Code example if applicable]
## When to Use
[Trigger conditions - what should activate this skill]
```
## Process
1. Review the session for extractable patterns
2. Identify the most valuable/reusable insight
3. Draft the skill file
4. Ask user to confirm before saving
5. Save to `~/.claude/skills/learned/`
## Notes
- Don't extract trivial fixes (typos, simple syntax errors)
- Don't extract one-time issues (specific API outages, etc.)
- Focus on patterns that will save time in future sessions
- Keep skills focused - one pattern per skill

32
.agent/knowledge/everything_claude/commands/loop-start.md Normal file
View File

@@ -0,0 +1,32 @@
# Loop Start Command
Start a managed autonomous loop pattern with safety defaults.
## Usage
`/loop-start [pattern] [--mode safe|fast]`
- `pattern`: `sequential`, `continuous-pr`, `rfc-dag`, `infinite`
- `--mode`:
- `safe` (default): strict quality gates and checkpoints
- `fast`: reduced gates for speed
## Flow
1. Confirm repository state and branch strategy.
2. Select loop pattern and model tier strategy.
3. Enable required hooks/profile for the chosen mode.
4. Create loop plan and write runbook under `.claude/plans/`.
5. Print commands to start and monitor the loop.
## Required Safety Checks
- Verify tests pass before first loop iteration.
- Ensure `ECC_HOOK_PROFILE` is not disabled globally.
- Ensure loop has explicit stop condition.
## Arguments
$ARGUMENTS:
- `<pattern>` optional (`sequential|continuous-pr|rfc-dag|infinite`)
- `--mode safe|fast` optional

24
.agent/knowledge/everything_claude/commands/loop-status.md Normal file
View File

@@ -0,0 +1,24 @@
# Loop Status Command
Inspect active loop state, progress, and failure signals.
## Usage
`/loop-status [--watch]`
## What to Report
- active loop pattern
- current phase and last successful checkpoint
- failing checks (if any)
- estimated time/cost drift
- recommended intervention (continue/pause/stop)
## Watch Mode
When `--watch` is present, refresh status periodically and surface state changes.
## Arguments
$ARGUMENTS:
- `--watch` optional

26
.agent/knowledge/everything_claude/commands/model-route.md Normal file
View File

@@ -0,0 +1,26 @@
# Model Route Command
Recommend the best model tier for the current task by complexity and budget.
## Usage
`/model-route [task-description] [--budget low|med|high]`
## Routing Heuristic
- `haiku`: deterministic, low-risk mechanical changes
- `sonnet`: default for implementation and refactors
- `opus`: architecture, deep review, ambiguous requirements
## Required Output
- recommended model
- confidence level
- why this model fits
- fallback model if first attempt fails
## Arguments
$ARGUMENTS:
- `[task-description]` optional free-text
- `--budget low|med|high` optional

158
.agent/knowledge/everything_claude/commands/multi-backend.md Normal file
View File

@@ -0,0 +1,158 @@
# Backend - Backend-Focused Development
Backend-focused workflow (Research → Ideation → Plan → Execute → Optimize → Review), Codex-led.
## Usage
```bash
/backend <backend task description>
```
## Context
- Backend task: $ARGUMENTS
- Codex-led, Gemini for auxiliary reference
- Applicable: API design, algorithm implementation, database optimization, business logic
## Your Role
You are the **Backend Orchestrator**, coordinating multi-model collaboration for server-side tasks (Research → Ideation → Plan → Execute → Optimize → Review).
**Collaborative Models**:
- **Codex** – Backend logic, algorithms (**Backend authority, trustworthy**)
- **Gemini** – Frontend perspective (**Backend opinions for reference only**)
- **Claude (self)** – Orchestration, planning, execution, delivery
---
## Multi-Model Call Specification
**Call Syntax**:
```
# New session call
Bash({
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend codex - \"$PWD\" <<'EOF'
ROLE_FILE: <role prompt path>
<TASK>
Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
Context: <project context and analysis from previous phases>
</TASK>
OUTPUT: Expected output format
EOF",
run_in_background: false,
timeout: 3600000,
description: "Brief description"
})
# Resume session call
Bash({
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend codex resume <SESSION_ID> - \"$PWD\" <<'EOF'
ROLE_FILE: <role prompt path>
<TASK>
Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
Context: <project context and analysis from previous phases>
</TASK>
OUTPUT: Expected output format
EOF",
run_in_background: false,
timeout: 3600000,
description: "Brief description"
})
```
**Role Prompts**:
| Phase | Codex |
|-------|-------|
| Analysis | `~/.claude/.ccg/prompts/codex/analyzer.md` |
| Planning | `~/.claude/.ccg/prompts/codex/architect.md` |
| Review | `~/.claude/.ccg/prompts/codex/reviewer.md` |
**Session Reuse**: Each call returns `SESSION_ID: xxx`, use `resume xxx` for subsequent phases. Save `CODEX_SESSION` in Phase 2, use `resume` in Phases 3 and 5.
---
## Communication Guidelines
1. Start responses with mode label `[Mode: X]`, initial is `[Mode: Research]`
2. Follow strict sequence: `Research → Ideation → Plan → Execute → Optimize → Review`
3. Use `AskUserQuestion` tool for user interaction when needed (e.g., confirmation/selection/approval)
---
## Core Workflow
### Phase 0: Prompt Enhancement (Optional)
`[Mode: Prepare]` - If ace-tool MCP available, call `mcp__ace-tool__enhance_prompt`, **replace original $ARGUMENTS with enhanced result for subsequent Codex calls**. If unavailable, use `$ARGUMENTS` as-is.
### Phase 1: Research
`[Mode: Research]` - Understand requirements and gather context
1. **Code Retrieval** (if ace-tool MCP available): Call `mcp__ace-tool__search_context` to retrieve existing APIs, data models, service architecture. If unavailable, use built-in tools: `Glob` for file discovery, `Grep` for symbol/API search, `Read` for context gathering, `Task` (Explore agent) for deeper exploration.
2. Requirement completeness score (0-10): >=7 continue, <7 stop and supplement
### Phase 2: Ideation
`[Mode: Ideation]` - Codex-led analysis
**MUST call Codex** (follow call specification above):
- ROLE_FILE: `~/.claude/.ccg/prompts/codex/analyzer.md`
- Requirement: Enhanced requirement (or $ARGUMENTS if not enhanced)
- Context: Project context from Phase 1
- OUTPUT: Technical feasibility analysis, recommended solutions (at least 2), risk assessment
**Save SESSION_ID** (`CODEX_SESSION`) for subsequent phase reuse.
Output solutions (at least 2), wait for user selection.
### Phase 3: Planning
`[Mode: Plan]` - Codex-led planning
**MUST call Codex** (use `resume <CODEX_SESSION>` to reuse session):
- ROLE_FILE: `~/.claude/.ccg/prompts/codex/architect.md`
- Requirement: User's selected solution
- Context: Analysis results from Phase 2
- OUTPUT: File structure, function/class design, dependency relationships
Claude synthesizes plan, save to `.claude/plan/task-name.md` after user approval.
### Phase 4: Implementation
`[Mode: Execute]` - Code development
- Strictly follow approved plan
- Follow existing project code standards
- Ensure error handling, security, performance optimization
### Phase 5: Optimization
`[Mode: Optimize]` - Codex-led review
**MUST call Codex** (follow call specification above):
- ROLE_FILE: `~/.claude/.ccg/prompts/codex/reviewer.md`
- Requirement: Review the following backend code changes
- Context: git diff or code content
- OUTPUT: Security, performance, error handling, API compliance issues list
Integrate review feedback, execute optimization after user confirmation.
### Phase 6: Quality Review
`[Mode: Review]` - Final evaluation
- Check completion against plan
- Run tests to verify functionality
- Report issues and recommendations
---
## Key Rules
1. **Codex backend opinions are trustworthy**
2. **Gemini backend opinions for reference only**
3. External models have **zero filesystem write access**
4. Claude handles all code writes and file operations

315
.agent/knowledge/everything_claude/commands/multi-execute.md Normal file
View File

@@ -0,0 +1,315 @@
# Execute - Multi-Model Collaborative Execution
Multi-model collaborative execution - Get prototype from plan → Claude refactors and implements → Multi-model audit and delivery.
$ARGUMENTS
---
## Core Protocols
- **Language Protocol**: Use **English** when interacting with tools/models, communicate with user in their language
- **Code Sovereignty**: External models have **zero filesystem write access**, all modifications by Claude
- **Dirty Prototype Refactoring**: Treat Codex/Gemini Unified Diff as "dirty prototype", must refactor to production-grade code
- **Stop-Loss Mechanism**: Do not proceed to next phase until current phase output is validated
- **Prerequisite**: Only execute after user explicitly replies "Y" to `/ccg:plan` output (if missing, must confirm first)
---
## Multi-Model Call Specification
**Call Syntax** (parallel: use `run_in_background: true`):
```
# Resume session call (recommended) - Implementation Prototype
Bash({
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}resume <SESSION_ID> - \"$PWD\" <<'EOF'
ROLE_FILE: <role prompt path>
<TASK>
Requirement: <task description>
Context: <plan content + target files>
</TASK>
OUTPUT: Unified Diff Patch ONLY. Strictly prohibit any actual modifications.
EOF",
run_in_background: true,
timeout: 3600000,
description: "Brief description"
})
# New session call - Implementation Prototype
Bash({
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}- \"$PWD\" <<'EOF'
ROLE_FILE: <role prompt path>
<TASK>
Requirement: <task description>
Context: <plan content + target files>
</TASK>
OUTPUT: Unified Diff Patch ONLY. Strictly prohibit any actual modifications.
EOF",
run_in_background: true,
timeout: 3600000,
description: "Brief description"
})
```
**Audit Call Syntax** (Code Review / Audit):
```
Bash({
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}resume <SESSION_ID> - \"$PWD\" <<'EOF'
ROLE_FILE: <role prompt path>
<TASK>
Scope: Audit the final code changes.
Inputs:
- The applied patch (git diff / final unified diff)
- The touched files (relevant excerpts if needed)
Constraints:
- Do NOT modify any files.
- Do NOT output tool commands that assume filesystem access.
</TASK>
OUTPUT:
1) A prioritized list of issues (severity, file, rationale)
2) Concrete fixes; if code changes are needed, include a Unified Diff Patch in a fenced code block.
EOF",
run_in_background: true,
timeout: 3600000,
description: "Brief description"
})
```
**Model Parameter Notes**:
- `{{GEMINI_MODEL_FLAG}}`: When using `--backend gemini`, replace with `--gemini-model gemini-3-pro-preview` (note trailing space); use empty string for codex
**Role Prompts**:
| Phase | Codex | Gemini |
|-------|-------|--------|
| Implementation | `~/.claude/.ccg/prompts/codex/architect.md` | `~/.claude/.ccg/prompts/gemini/frontend.md` |
| Review | `~/.claude/.ccg/prompts/codex/reviewer.md` | `~/.claude/.ccg/prompts/gemini/reviewer.md` |
**Session Reuse**: If `/ccg:plan` provided SESSION_ID, use `resume <SESSION_ID>` to reuse context.
**Wait for Background Tasks** (max timeout 600000ms = 10 minutes):
```
TaskOutput({ task_id: "<task_id>", block: true, timeout: 600000 })
```
**IMPORTANT**:
- Must specify `timeout: 600000`, otherwise default 30 seconds will cause premature timeout
- If still incomplete after 10 minutes, continue polling with `TaskOutput`, **NEVER kill the process**
- If waiting is skipped due to timeout, **MUST call `AskUserQuestion` to ask user whether to continue waiting or kill task**
---
## Execution Workflow
**Execute Task**: $ARGUMENTS
### Phase 0: Read Plan
`[Mode: Prepare]`
1. **Identify Input Type**:
- Plan file path (e.g., `.claude/plan/xxx.md`)
- Direct task description
2. **Read Plan Content**:
- If plan file path provided, read and parse
- Extract: task type, implementation steps, key files, SESSION_ID
3. **Pre-Execution Confirmation**:
- If input is "direct task description" or plan missing `SESSION_ID` / key files: confirm with user first
- If cannot confirm user replied "Y" to plan: must confirm again before proceeding
4. **Task Type Routing**:
| Task Type | Detection | Route |
|-----------|-----------|-------|
| **Frontend** | Pages, components, UI, styles, layout | Gemini |
| **Backend** | API, interfaces, database, logic, algorithms | Codex |
| **Fullstack** | Contains both frontend and backend | Codex ∥ Gemini parallel |
---
### Phase 1: Quick Context Retrieval
`[Mode: Retrieval]`
**If ace-tool MCP is available**, use it for quick context retrieval:
Based on "Key Files" list in plan, call `mcp__ace-tool__search_context`:
```
mcp__ace-tool__search_context({
query: "<semantic query based on plan content, including key files, modules, function names>",
project_root_path: "$PWD"
})
```
**Retrieval Strategy**:
- Extract target paths from plan's "Key Files" table
- Build semantic query covering: entry files, dependency modules, related type definitions
- If results insufficient, add 1-2 recursive retrievals
**If ace-tool MCP is NOT available**, use Claude Code built-in tools as fallback:
1. **Glob**: Find target files from plan's "Key Files" table (e.g., `Glob("src/components/**/*.tsx")`)
2. **Grep**: Search for key symbols, function names, type definitions across the codebase
3. **Read**: Read the discovered files to gather complete context
4. **Task (Explore agent)**: For broader exploration, use `Task` with `subagent_type: "Explore"`
**After Retrieval**:
- Organize retrieved code snippets
- Confirm complete context for implementation
- Proceed to Phase 3
---
### Phase 3: Prototype Acquisition
`[Mode: Prototype]`
**Route Based on Task Type**:
#### Route A: Frontend/UI/Styles → Gemini
**Limit**: Context < 32k tokens
1. Call Gemini (use `~/.claude/.ccg/prompts/gemini/frontend.md`)
2. Input: Plan content + retrieved context + target files
3. OUTPUT: `Unified Diff Patch ONLY. Strictly prohibit any actual modifications.`
4. **Gemini is frontend design authority, its CSS/React/Vue prototype is the final visual baseline**
5. **WARNING**: Ignore Gemini's backend logic suggestions
6. If plan contains `GEMINI_SESSION`: prefer `resume <GEMINI_SESSION>`
#### Route B: Backend/Logic/Algorithms → Codex
1. Call Codex (use `~/.claude/.ccg/prompts/codex/architect.md`)
2. Input: Plan content + retrieved context + target files
3. OUTPUT: `Unified Diff Patch ONLY. Strictly prohibit any actual modifications.`
4. **Codex is backend logic authority, leverage its logical reasoning and debug capabilities**
5. If plan contains `CODEX_SESSION`: prefer `resume <CODEX_SESSION>`
#### Route C: Fullstack → Parallel Calls
1. **Parallel Calls** (`run_in_background: true`):
- Gemini: Handle frontend part
- Codex: Handle backend part
2. Wait for both models' complete results with `TaskOutput`
3. Each uses corresponding `SESSION_ID` from plan for `resume` (create new session if missing)
**Follow the `IMPORTANT` instructions in `Multi-Model Call Specification` above**
---
### Phase 4: Code Implementation
`[Mode: Implement]`
**Claude as Code Sovereign executes the following steps**:
1. **Read Diff**: Parse Unified Diff Patch returned by Codex/Gemini
2. **Mental Sandbox**:
- Simulate applying Diff to target files
- Check logical consistency
- Identify potential conflicts or side effects
3. **Refactor and Clean**:
- Refactor "dirty prototype" to **highly readable, maintainable, enterprise-grade code**
- Remove redundant code
- Ensure compliance with project's existing code standards
- **Do not generate comments/docs unless necessary**, code should be self-explanatory
4. **Minimal Scope**:
- Changes limited to requirement scope only
- **Mandatory review** for side effects
- Make targeted corrections
5. **Apply Changes**:
- Use Edit/Write tools to execute actual modifications
- **Only modify necessary code**, never affect user's other existing functionality
6. **Self-Verification** (strongly recommended):
- Run project's existing lint / typecheck / tests (prioritize minimal related scope)
- If failed: fix regressions first, then proceed to Phase 5
---
### Phase 5: Audit and Delivery
`[Mode: Audit]`
#### 5.1 Automatic Audit
**After changes take effect, MUST immediately parallel call** Codex and Gemini for Code Review:
1. **Codex Review** (`run_in_background: true`):
- ROLE_FILE: `~/.claude/.ccg/prompts/codex/reviewer.md`
- Input: Changed Diff + target files
- Focus: Security, performance, error handling, logic correctness
2. **Gemini Review** (`run_in_background: true`):
- ROLE_FILE: `~/.claude/.ccg/prompts/gemini/reviewer.md`
- Input: Changed Diff + target files
- Focus: Accessibility, design consistency, user experience
Wait for both models' complete review results with `TaskOutput`. Prefer reusing Phase 3 sessions (`resume <SESSION_ID>`) for context consistency.
#### 5.2 Integrate and Fix
1. Synthesize Codex + Gemini review feedback
2. Weigh by trust rules: Backend follows Codex, Frontend follows Gemini
3. Execute necessary fixes
4. Repeat Phase 5.1 as needed (until risk is acceptable)
#### 5.3 Delivery Confirmation
After audit passes, report to user:
```markdown
## Execution Complete
### Change Summary
| File | Operation | Description |
|------|-----------|-------------|
| path/to/file.ts | Modified | Description |
### Audit Results
- Codex: <Passed/Found N issues>
- Gemini: <Passed/Found N issues>
### Recommendations
1. [ ] <Suggested test steps>
2. [ ] <Suggested verification steps>
```
---
## Key Rules
1. **Code Sovereignty** – All file modifications by Claude, external models have zero write access
2. **Dirty Prototype Refactoring** – Codex/Gemini output treated as draft, must refactor
3. **Trust Rules** – Backend follows Codex, Frontend follows Gemini
4. **Minimal Changes** – Only modify necessary code, no side effects
5. **Mandatory Audit** – Must perform multi-model Code Review after changes
---
## Usage
```bash
# Execute plan file
/ccg:execute .claude/plan/feature-name.md
# Execute task directly (for plans already discussed in context)
/ccg:execute implement user authentication based on previous plan
```
---
## Relationship with /ccg:plan
1. `/ccg:plan` generates plan + SESSION_ID
2. User confirms with "Y"
3. `/ccg:execute` reads plan, reuses SESSION_ID, executes implementation

158
.agent/knowledge/everything_claude/commands/multi-frontend.md Normal file
View File

@@ -0,0 +1,158 @@
# Frontend - Frontend-Focused Development
Frontend-focused workflow (Research → Ideation → Plan → Execute → Optimize → Review), Gemini-led.
## Usage
```bash
/frontend <UI task description>
```
## Context
- Frontend task: $ARGUMENTS
- Gemini-led, Codex for auxiliary reference
- Applicable: Component design, responsive layout, UI animations, style optimization
## Your Role
You are the **Frontend Orchestrator**, coordinating multi-model collaboration for UI/UX tasks (Research → Ideation → Plan → Execute → Optimize → Review).
**Collaborative Models**:
- **Gemini** – Frontend UI/UX (**Frontend authority, trustworthy**)
- **Codex** – Backend perspective (**Frontend opinions for reference only**)
- **Claude (self)** – Orchestration, planning, execution, delivery
---
## Multi-Model Call Specification
**Call Syntax**:
```
# New session call
Bash({
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend gemini --gemini-model gemini-3-pro-preview - \"$PWD\" <<'EOF'
ROLE_FILE: <role prompt path>
<TASK>
Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
Context: <project context and analysis from previous phases>
</TASK>
OUTPUT: Expected output format
EOF",
run_in_background: false,
timeout: 3600000,
description: "Brief description"
})
# Resume session call
Bash({
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend gemini --gemini-model gemini-3-pro-preview resume <SESSION_ID> - \"$PWD\" <<'EOF'
ROLE_FILE: <role prompt path>
<TASK>
Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
Context: <project context and analysis from previous phases>
</TASK>
OUTPUT: Expected output format
EOF",
run_in_background: false,
timeout: 3600000,
description: "Brief description"
})
```
**Role Prompts**:
| Phase | Gemini |
|-------|--------|
| Analysis | `~/.claude/.ccg/prompts/gemini/analyzer.md` |
| Planning | `~/.claude/.ccg/prompts/gemini/architect.md` |
| Review | `~/.claude/.ccg/prompts/gemini/reviewer.md` |
**Session Reuse**: Each call returns `SESSION_ID: xxx`, use `resume xxx` for subsequent phases. Save `GEMINI_SESSION` in Phase 2, use `resume` in Phases 3 and 5.
---
## Communication Guidelines
1. Start responses with mode label `[Mode: X]`, initial is `[Mode: Research]`
2. Follow strict sequence: `Research → Ideation → Plan → Execute → Optimize → Review`
3. Use `AskUserQuestion` tool for user interaction when needed (e.g., confirmation/selection/approval)
---
## Core Workflow
### Phase 0: Prompt Enhancement (Optional)
`[Mode: Prepare]` - If ace-tool MCP available, call `mcp__ace-tool__enhance_prompt`, **replace original $ARGUMENTS with enhanced result for subsequent Gemini calls**. If unavailable, use `$ARGUMENTS` as-is.
### Phase 1: Research
`[Mode: Research]` - Understand requirements and gather context
1. **Code Retrieval** (if ace-tool MCP available): Call `mcp__ace-tool__search_context` to retrieve existing components, styles, design system. If unavailable, use built-in tools: `Glob` for file discovery, `Grep` for component/style search, `Read` for context gathering, `Task` (Explore agent) for deeper exploration.
2. Requirement completeness score (0-10): >=7 continue, <7 stop and supplement
### Phase 2: Ideation
`[Mode: Ideation]` - Gemini-led analysis
**MUST call Gemini** (follow call specification above):
- ROLE_FILE: `~/.claude/.ccg/prompts/gemini/analyzer.md`
- Requirement: Enhanced requirement (or $ARGUMENTS if not enhanced)
- Context: Project context from Phase 1
- OUTPUT: UI feasibility analysis, recommended solutions (at least 2), UX evaluation
**Save SESSION_ID** (`GEMINI_SESSION`) for subsequent phase reuse.
Output solutions (at least 2), wait for user selection.
### Phase 3: Planning
`[Mode: Plan]` - Gemini-led planning
**MUST call Gemini** (use `resume <GEMINI_SESSION>` to reuse session):
- ROLE_FILE: `~/.claude/.ccg/prompts/gemini/architect.md`
- Requirement: User's selected solution
- Context: Analysis results from Phase 2
- OUTPUT: Component structure, UI flow, styling approach
Claude synthesizes plan, save to `.claude/plan/task-name.md` after user approval.
### Phase 4: Implementation
`[Mode: Execute]` - Code development
- Strictly follow approved plan
- Follow existing project design system and code standards
- Ensure responsiveness, accessibility
### Phase 5: Optimization
`[Mode: Optimize]` - Gemini-led review
**MUST call Gemini** (follow call specification above):
- ROLE_FILE: `~/.claude/.ccg/prompts/gemini/reviewer.md`
- Requirement: Review the following frontend code changes
- Context: git diff or code content
- OUTPUT: Accessibility, responsiveness, performance, design consistency issues list
Integrate review feedback, execute optimization after user confirmation.
### Phase 6: Quality Review
`[Mode: Review]` - Final evaluation
- Check completion against plan
- Verify responsiveness and accessibility
- Report issues and recommendations
---
## Key Rules
1. **Gemini frontend opinions are trustworthy**
2. **Codex frontend opinions for reference only**
3. External models have **zero filesystem write access**
4. Claude handles all code writes and file operations

268
.agent/knowledge/everything_claude/commands/multi-plan.md Normal file
View File

@@ -0,0 +1,268 @@
# Plan - Multi-Model Collaborative Planning
Multi-model collaborative planning - Context retrieval + Dual-model analysis → Generate step-by-step implementation plan.
$ARGUMENTS
---
## Core Protocols
- **Language Protocol**: Use **English** when interacting with tools/models, communicate with user in their language
- **Mandatory Parallel**: Codex/Gemini calls MUST use `run_in_background: true` (including single model calls, to avoid blocking main thread)
- **Code Sovereignty**: External models have **zero filesystem write access**, all modifications by Claude
- **Stop-Loss Mechanism**: Do not proceed to next phase until current phase output is validated
- **Planning Only**: This command allows reading context and writing to `.claude/plan/*` plan files, but **NEVER modify production code**
---
## Multi-Model Call Specification
**Call Syntax** (parallel: use `run_in_background: true`):
```
Bash({
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}- \"$PWD\" <<'EOF'
ROLE_FILE: <role prompt path>
<TASK>
Requirement: <enhanced requirement>
Context: <retrieved project context>
</TASK>
OUTPUT: Step-by-step implementation plan with pseudo-code. DO NOT modify any files.
EOF",
run_in_background: true,
timeout: 3600000,
description: "Brief description"
})
```
**Model Parameter Notes**:
- `{{GEMINI_MODEL_FLAG}}`: When using `--backend gemini`, replace with `--gemini-model gemini-3-pro-preview` (note trailing space); use empty string for codex
**Role Prompts**:
| Phase | Codex | Gemini |
|-------|-------|--------|
| Analysis | `~/.claude/.ccg/prompts/codex/analyzer.md` | `~/.claude/.ccg/prompts/gemini/analyzer.md` |
| Planning | `~/.claude/.ccg/prompts/codex/architect.md` | `~/.claude/.ccg/prompts/gemini/architect.md` |
**Session Reuse**: Each call returns `SESSION_ID: xxx` (typically output by wrapper), **MUST save** for subsequent `/ccg:execute` use.
**Wait for Background Tasks** (max timeout 600000ms = 10 minutes):
```
TaskOutput({ task_id: "<task_id>", block: true, timeout: 600000 })
```
**IMPORTANT**:
- Must specify `timeout: 600000`, otherwise default 30 seconds will cause premature timeout
- If still incomplete after 10 minutes, continue polling with `TaskOutput`, **NEVER kill the process**
- If waiting is skipped due to timeout, **MUST call `AskUserQuestion` to ask user whether to continue waiting or kill task**
---
## Execution Workflow
**Planning Task**: $ARGUMENTS
### Phase 1: Full Context Retrieval
`[Mode: Research]`
#### 1.1 Prompt Enhancement (MUST execute first)
**If ace-tool MCP is available**, call `mcp__ace-tool__enhance_prompt` tool:
```
mcp__ace-tool__enhance_prompt({
prompt: "$ARGUMENTS",
conversation_history: "<last 5-10 conversation turns>",
project_root_path: "$PWD"
})
```
Wait for enhanced prompt, **replace original $ARGUMENTS with enhanced result** for all subsequent phases.
**If ace-tool MCP is NOT available**: Skip this step and use the original `$ARGUMENTS` as-is for all subsequent phases.
#### 1.2 Context Retrieval
**If ace-tool MCP is available**, call `mcp__ace-tool__search_context` tool:
```
mcp__ace-tool__search_context({
query: "<semantic query based on enhanced requirement>",
project_root_path: "$PWD"
})
```
- Build semantic query using natural language (Where/What/How)
- **NEVER answer based on assumptions**
**If ace-tool MCP is NOT available**, use Claude Code built-in tools as fallback:
1. **Glob**: Find relevant files by pattern (e.g., `Glob("**/*.ts")`, `Glob("src/**/*.py")`)
2. **Grep**: Search for key symbols, function names, class definitions (e.g., `Grep("className|functionName")`)
3. **Read**: Read the discovered files to gather complete context
4. **Task (Explore agent)**: For deeper exploration, use `Task` with `subagent_type: "Explore"` to search across the codebase
#### 1.3 Completeness Check
- Must obtain **complete definitions and signatures** for relevant classes, functions, variables
- If context insufficient, trigger **recursive retrieval**
- Prioritize output: entry file + line number + key symbol name; add minimal code snippets only when necessary to resolve ambiguity
#### 1.4 Requirement Alignment
- If requirements still have ambiguity, **MUST** output guiding questions for user
- Until requirement boundaries are clear (no omissions, no redundancy)
### Phase 2: Multi-Model Collaborative Analysis
`[Mode: Analysis]`
#### 2.1 Distribute Inputs
**Parallel call** Codex and Gemini (`run_in_background: true`):
Distribute **original requirement** (without preset opinions) to both models:
1. **Codex Backend Analysis**:
- ROLE_FILE: `~/.claude/.ccg/prompts/codex/analyzer.md`
- Focus: Technical feasibility, architecture impact, performance considerations, potential risks
- OUTPUT: Multi-perspective solutions + pros/cons analysis
2. **Gemini Frontend Analysis**:
- ROLE_FILE: `~/.claude/.ccg/prompts/gemini/analyzer.md`
- Focus: UI/UX impact, user experience, visual design
- OUTPUT: Multi-perspective solutions + pros/cons analysis
Wait for both models' complete results with `TaskOutput`. **Save SESSION_ID** (`CODEX_SESSION` and `GEMINI_SESSION`).
#### 2.2 Cross-Validation
Integrate perspectives and iterate for optimization:
1. **Identify consensus** (strong signal)
2. **Identify divergence** (needs weighing)
3. **Complementary strengths**: Backend logic follows Codex, Frontend design follows Gemini
4. **Logical reasoning**: Eliminate logical gaps in solutions
#### 2.3 (Optional but Recommended) Dual-Model Plan Draft
To reduce risk of omissions in Claude's synthesized plan, can parallel have both models output "plan drafts" (still **NOT allowed** to modify files):
1. **Codex Plan Draft** (Backend authority):
- ROLE_FILE: `~/.claude/.ccg/prompts/codex/architect.md`
- OUTPUT: Step-by-step plan + pseudo-code (focus: data flow/edge cases/error handling/test strategy)
2. **Gemini Plan Draft** (Frontend authority):
- ROLE_FILE: `~/.claude/.ccg/prompts/gemini/architect.md`
- OUTPUT: Step-by-step plan + pseudo-code (focus: information architecture/interaction/accessibility/visual consistency)
Wait for both models' complete results with `TaskOutput`, record key differences in their suggestions.
#### 2.4 Generate Implementation Plan (Claude Final Version)
Synthesize both analyses, generate **Step-by-step Implementation Plan**:
```markdown
## Implementation Plan: <Task Name>
### Task Type
- [ ] Frontend (→ Gemini)
- [ ] Backend (→ Codex)
- [ ] Fullstack (→ Parallel)
### Technical Solution
<Optimal solution synthesized from Codex + Gemini analysis>
### Implementation Steps
1. <Step 1> - Expected deliverable
2. <Step 2> - Expected deliverable
...
### Key Files
| File | Operation | Description |
|------|-----------|-------------|
| path/to/file.ts:L10-L50 | Modify | Description |
### Risks and Mitigation
| Risk | Mitigation |
|------|------------|
### SESSION_ID (for /ccg:execute use)
- CODEX_SESSION: <session_id>
- GEMINI_SESSION: <session_id>
```
### Phase 2 End: Plan Delivery (Not Execution)
**`/ccg:plan` responsibilities end here, MUST execute the following actions**:
1. Present complete implementation plan to user (including pseudo-code)
2. Save plan to `.claude/plan/<feature-name>.md` (extract feature name from requirement, e.g., `user-auth`, `payment-module`)
3. Output prompt in **bold text** (MUST use actual saved file path):
---
**Plan generated and saved to `.claude/plan/actual-feature-name.md`**
**Please review the plan above. You can:**
- **Modify plan**: Tell me what needs adjustment, I'll update the plan
- **Execute plan**: Copy the following command to a new session
```
/ccg:execute .claude/plan/actual-feature-name.md
```
---
**NOTE**: The `actual-feature-name.md` above MUST be replaced with the actual saved filename!
4. **Immediately terminate current response** (Stop here. No more tool calls.)
**ABSOLUTELY FORBIDDEN**:
- Ask user "Y/N" then auto-execute (execution is `/ccg:execute`'s responsibility)
- Any write operations to production code
- Automatically call `/ccg:execute` or any implementation actions
- Continue triggering model calls when user hasn't explicitly requested modifications
---
## Plan Saving
After planning completes, save plan to:
- **First planning**: `.claude/plan/<feature-name>.md`
- **Iteration versions**: `.claude/plan/<feature-name>-v2.md`, `.claude/plan/<feature-name>-v3.md`...
Plan file write should complete before presenting plan to user.
---
## Plan Modification Flow
If user requests plan modifications:
1. Adjust plan content based on user feedback
2. Update `.claude/plan/<feature-name>.md` file
3. Re-present modified plan
4. Prompt user to review or execute again
---
## Next Steps
After user approves, **manually** execute:
```bash
/ccg:execute .claude/plan/<feature-name>.md
```
---
## Key Rules
1. **Plan only, no implementation** – This command does not execute any code changes
2. **No Y/N prompts** – Only present plan, let user decide next steps
3. **Trust Rules** – Backend follows Codex, Frontend follows Gemini
4. External models have **zero filesystem write access**
5. **SESSION_ID Handoff** – Plan must include `CODEX_SESSION` / `GEMINI_SESSION` at end (for `/ccg:execute resume <SESSION_ID>` use)

191
.agent/knowledge/everything_claude/commands/multi-workflow.md Normal file
View File

@@ -0,0 +1,191 @@
# Workflow - Multi-Model Collaborative Development
Multi-model collaborative development workflow (Research → Ideation → Plan → Execute → Optimize → Review), with intelligent routing: Frontend → Gemini, Backend → Codex.
Structured development workflow with quality gates, MCP services, and multi-model collaboration.
## Usage
```bash
/workflow <task description>
```
## Context
- Task to develop: $ARGUMENTS
- Structured 6-phase workflow with quality gates
- Multi-model collaboration: Codex (backend) + Gemini (frontend) + Claude (orchestration)
- MCP service integration (ace-tool, optional) for enhanced capabilities
## Your Role
You are the **Orchestrator**, coordinating a multi-model collaborative system (Research → Ideation → Plan → Execute → Optimize → Review). Communicate concisely and professionally for experienced developers.
**Collaborative Models**:
- **ace-tool MCP** (optional) – Code retrieval + Prompt enhancement
- **Codex** – Backend logic, algorithms, debugging (**Backend authority, trustworthy**)
- **Gemini** – Frontend UI/UX, visual design (**Frontend expert, backend opinions for reference only**)
- **Claude (self)** – Orchestration, planning, execution, delivery
---
## Multi-Model Call Specification
**Call syntax** (parallel: `run_in_background: true`, sequential: `false`):
```
# New session call
Bash({
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}- \"$PWD\" <<'EOF'
ROLE_FILE: <role prompt path>
<TASK>
Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
Context: <project context and analysis from previous phases>
</TASK>
OUTPUT: Expected output format
EOF",
run_in_background: true,
timeout: 3600000,
description: "Brief description"
})
# Resume session call
Bash({
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}resume <SESSION_ID> - \"$PWD\" <<'EOF'
ROLE_FILE: <role prompt path>
<TASK>
Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
Context: <project context and analysis from previous phases>
</TASK>
OUTPUT: Expected output format
EOF",
run_in_background: true,
timeout: 3600000,
description: "Brief description"
})
```
**Model Parameter Notes**:
- `{{GEMINI_MODEL_FLAG}}`: When using `--backend gemini`, replace with `--gemini-model gemini-3-pro-preview` (note trailing space); use empty string for codex
**Role Prompts**:
| Phase | Codex | Gemini |
|-------|-------|--------|
| Analysis | `~/.claude/.ccg/prompts/codex/analyzer.md` | `~/.claude/.ccg/prompts/gemini/analyzer.md` |
| Planning | `~/.claude/.ccg/prompts/codex/architect.md` | `~/.claude/.ccg/prompts/gemini/architect.md` |
| Review | `~/.claude/.ccg/prompts/codex/reviewer.md` | `~/.claude/.ccg/prompts/gemini/reviewer.md` |
**Session Reuse**: Each call returns `SESSION_ID: xxx`, use `resume xxx` subcommand for subsequent phases (note: `resume`, not `--resume`).
**Parallel Calls**: Use `run_in_background: true` to start, wait for results with `TaskOutput`. **Must wait for all models to return before proceeding to next phase**.
**Wait for Background Tasks** (use max timeout 600000ms = 10 minutes):
```
TaskOutput({ task_id: "<task_id>", block: true, timeout: 600000 })
```
**IMPORTANT**:
- Must specify `timeout: 600000`, otherwise default 30 seconds will cause premature timeout.
- If still incomplete after 10 minutes, continue polling with `TaskOutput`, **NEVER kill the process**.
- If waiting is skipped due to timeout, **MUST call `AskUserQuestion` to ask user whether to continue waiting or kill task. Never kill directly.**
---
## Communication Guidelines
1. Start responses with mode label `[Mode: X]`, initial is `[Mode: Research]`.
2. Follow strict sequence: `Research → Ideation → Plan → Execute → Optimize → Review`.
3. Request user confirmation after each phase completion.
4. Force stop when score < 7 or user does not approve.
5. Use `AskUserQuestion` tool for user interaction when needed (e.g., confirmation/selection/approval).
## When to Use External Orchestration
Use external tmux/worktree orchestration when the work must be split across parallel workers that need isolated git state, independent terminals, or separate build/test execution. Use in-process subagents for lightweight analysis, planning, or review where the main session remains the only writer.
```bash
node scripts/orchestrate-worktrees.js .claude/plan/workflow-e2e-test.json --execute
```
---
## Execution Workflow
**Task Description**: $ARGUMENTS
### Phase 1: Research & Analysis
`[Mode: Research]` - Understand requirements and gather context:
1. **Prompt Enhancement** (if ace-tool MCP available): Call `mcp__ace-tool__enhance_prompt`, **replace original $ARGUMENTS with enhanced result for all subsequent Codex/Gemini calls**. If unavailable, use `$ARGUMENTS` as-is.
2. **Context Retrieval** (if ace-tool MCP available): Call `mcp__ace-tool__search_context`. If unavailable, use built-in tools: `Glob` for file discovery, `Grep` for symbol search, `Read` for context gathering, `Task` (Explore agent) for deeper exploration.
3. **Requirement Completeness Score** (0-10):
- Goal clarity (0-3), Expected outcome (0-3), Scope boundaries (0-2), Constraints (0-2)
- ≥7: Continue | <7: Stop, ask clarifying questions
### Phase 2: Solution Ideation
`[Mode: Ideation]` - Multi-model parallel analysis:
**Parallel Calls** (`run_in_background: true`):
- Codex: Use analyzer prompt, output technical feasibility, solutions, risks
- Gemini: Use analyzer prompt, output UI feasibility, solutions, UX evaluation
Wait for results with `TaskOutput`. **Save SESSION_ID** (`CODEX_SESSION` and `GEMINI_SESSION`).
**Follow the `IMPORTANT` instructions in `Multi-Model Call Specification` above**
Synthesize both analyses, output solution comparison (at least 2 options), wait for user selection.
### Phase 3: Detailed Planning
`[Mode: Plan]` - Multi-model collaborative planning:
**Parallel Calls** (resume session with `resume <SESSION_ID>`):
- Codex: Use architect prompt + `resume $CODEX_SESSION`, output backend architecture
- Gemini: Use architect prompt + `resume $GEMINI_SESSION`, output frontend architecture
Wait for results with `TaskOutput`.
**Follow the `IMPORTANT` instructions in `Multi-Model Call Specification` above**
**Claude Synthesis**: Adopt Codex backend plan + Gemini frontend plan, save to `.claude/plan/task-name.md` after user approval.
### Phase 4: Implementation
`[Mode: Execute]` - Code development:
- Strictly follow approved plan
- Follow existing project code standards
- Request feedback at key milestones
### Phase 5: Code Optimization
`[Mode: Optimize]` - Multi-model parallel review:
**Parallel Calls**:
- Codex: Use reviewer prompt, focus on security, performance, error handling
- Gemini: Use reviewer prompt, focus on accessibility, design consistency
Wait for results with `TaskOutput`. Integrate review feedback, execute optimization after user confirmation.
**Follow the `IMPORTANT` instructions in `Multi-Model Call Specification` above**
### Phase 6: Quality Review
`[Mode: Review]` - Final evaluation:
- Check completion against plan
- Run tests to verify functionality
- Report issues and recommendations
- Request final user confirmation
---
## Key Rules
1. Phase sequence cannot be skipped (unless user explicitly instructs)
2. External models have **zero filesystem write access**, all modifications by Claude
3. **Force stop** when score < 7 or user does not approve

231
.agent/knowledge/everything_claude/commands/orchestrate.md Normal file
View File

@@ -0,0 +1,231 @@
---
description: Sequential and tmux/worktree orchestration guidance for multi-agent workflows.
---
# Orchestrate Command
Sequential agent workflow for complex tasks.
## Usage
`/orchestrate [workflow-type] [task-description]`
## Workflow Types
### feature
Full feature implementation workflow:
```
planner -> tdd-guide -> code-reviewer -> security-reviewer
```
### bugfix
Bug investigation and fix workflow:
```
planner -> tdd-guide -> code-reviewer
```
### refactor
Safe refactoring workflow:
```
architect -> code-reviewer -> tdd-guide
```
### security
Security-focused review:
```
security-reviewer -> code-reviewer -> architect
```
## Execution Pattern
For each agent in the workflow:
1. **Invoke agent** with context from previous agent
2. **Collect output** as structured handoff document
3. **Pass to next agent** in chain
4. **Aggregate results** into final report
## Handoff Document Format
Between agents, create handoff document:
```markdown
## HANDOFF: [previous-agent] -> [next-agent]
### Context
[Summary of what was done]
### Findings
[Key discoveries or decisions]
### Files Modified
[List of files touched]
### Open Questions
[Unresolved items for next agent]
### Recommendations
[Suggested next steps]
```
## Example: Feature Workflow
```
/orchestrate feature "Add user authentication"
```
Executes:
1. **Planner Agent**
- Analyzes requirements
- Creates implementation plan
- Identifies dependencies
- Output: `HANDOFF: planner -> tdd-guide`
2. **TDD Guide Agent**
- Reads planner handoff
- Writes tests first
- Implements to pass tests
- Output: `HANDOFF: tdd-guide -> code-reviewer`
3. **Code Reviewer Agent**
- Reviews implementation
- Checks for issues
- Suggests improvements
- Output: `HANDOFF: code-reviewer -> security-reviewer`
4. **Security Reviewer Agent**
- Security audit
- Vulnerability check
- Final approval
- Output: Final Report
## Final Report Format
```
ORCHESTRATION REPORT
====================
Workflow: feature
Task: Add user authentication
Agents: planner -> tdd-guide -> code-reviewer -> security-reviewer
SUMMARY
-------
[One paragraph summary]
AGENT OUTPUTS
-------------
Planner: [summary]
TDD Guide: [summary]
Code Reviewer: [summary]
Security Reviewer: [summary]
FILES CHANGED
-------------
[List all files modified]
TEST RESULTS
------------
[Test pass/fail summary]
SECURITY STATUS
---------------
[Security findings]
RECOMMENDATION
--------------
[SHIP / NEEDS WORK / BLOCKED]
```
## Parallel Execution
For independent checks, run agents in parallel:
```markdown
### Parallel Phase
Run simultaneously:
- code-reviewer (quality)
- security-reviewer (security)
- architect (design)
### Merge Results
Combine outputs into single report
```
For external tmux-pane workers with separate git worktrees, use `node scripts/orchestrate-worktrees.js plan.json --execute`. The built-in orchestration pattern stays in-process; the helper is for long-running or cross-harness sessions.
When workers need to see dirty or untracked local files from the main checkout, add `seedPaths` to the plan file. ECC overlays only those selected paths into each worker worktree after `git worktree add`, which keeps the branch isolated while still exposing in-flight local scripts, plans, or docs.
```json
{
"sessionName": "workflow-e2e",
"seedPaths": [
"scripts/orchestrate-worktrees.js",
"scripts/lib/tmux-worktree-orchestrator.js",
".claude/plan/workflow-e2e-test.json"
],
"workers": [
{ "name": "docs", "task": "Update orchestration docs." }
]
}
```
To export a control-plane snapshot for a live tmux/worktree session, run:
```bash
node scripts/orchestration-status.js .claude/plan/workflow-visual-proof.json
```
The snapshot includes session activity, tmux pane metadata, worker states, objectives, seeded overlays, and recent handoff summaries in JSON form.
## Operator Command-Center Handoff
When the workflow spans multiple sessions, worktrees, or tmux panes, append a control-plane block to the final handoff:
```markdown
CONTROL PLANE
-------------
Sessions:
- active session ID or alias
- branch + worktree path for each active worker
- tmux pane or detached session name when applicable
Diffs:
- git status summary
- git diff --stat for touched files
- merge/conflict risk notes
Approvals:
- pending user approvals
- blocked steps awaiting confirmation
Telemetry:
- last activity timestamp or idle signal
- estimated token or cost drift
- policy events raised by hooks or reviewers
```
This keeps planner, implementer, reviewer, and loop workers legible from the operator surface.
## Arguments
$ARGUMENTS:
- `feature <description>` - Full feature workflow
- `bugfix <description>` - Bug fix workflow
- `refactor <description>` - Refactoring workflow
- `security <description>` - Security review workflow
- `custom <agents> <description>` - Custom agent sequence
## Custom Workflow Example
```
/orchestrate custom "architect,tdd-guide,code-reviewer" "Redesign caching layer"
```
## Tips
1. **Start with planner** for complex features
2. **Always include code-reviewer** before merge
3. **Use security-reviewer** for auth/payment/PII
4. **Keep handoffs concise** - focus on what next agent needs
5. **Run verification** between agents if needed

115
.agent/knowledge/everything_claude/commands/plan.md Normal file
View File

@@ -0,0 +1,115 @@
---
description: Restate requirements, assess risks, and create step-by-step implementation plan. WAIT for user CONFIRM before touching any code.
---
# Plan Command
This command invokes the **planner** agent to create a comprehensive implementation plan before writing any code.
## What This Command Does
1. **Restate Requirements** - Clarify what needs to be built
2. **Identify Risks** - Surface potential issues and blockers
3. **Create Step Plan** - Break down implementation into phases
4. **Wait for Confirmation** - MUST receive user approval before proceeding
## When to Use
Use `/plan` when:
- Starting a new feature
- Making significant architectural changes
- Working on complex refactoring
- Multiple files/components will be affected
- Requirements are unclear or ambiguous
## How It Works
The planner agent will:
1. **Analyze the request** and restate requirements in clear terms
2. **Break down into phases** with specific, actionable steps
3. **Identify dependencies** between components
4. **Assess risks** and potential blockers
5. **Estimate complexity** (High/Medium/Low)
6. **Present the plan** and WAIT for your explicit confirmation
## Example Usage
```
User: /plan I need to add real-time notifications when markets resolve
Agent (planner):
# Implementation Plan: Real-Time Market Resolution Notifications
## Requirements Restatement
- Send notifications to users when markets they're watching resolve
- Support multiple notification channels (in-app, email, webhook)
- Ensure notifications are delivered reliably
- Include market outcome and user's position result
## Implementation Phases
### Phase 1: Database Schema
- Add notifications table with columns: id, user_id, market_id, type, status, created_at
- Add user_notification_preferences table for channel preferences
- Create indexes on user_id and market_id for performance
### Phase 2: Notification Service
- Create notification service in lib/notifications.ts
- Implement notification queue using BullMQ/Redis
- Add retry logic for failed deliveries
- Create notification templates
### Phase 3: Integration Points
- Hook into market resolution logic (when status changes to "resolved")
- Query all users with positions in market
- Enqueue notifications for each user
### Phase 4: Frontend Components
- Create NotificationBell component in header
- Add NotificationList modal
- Implement real-time updates via Supabase subscriptions
- Add notification preferences page
## Dependencies
- Redis (for queue)
- Email service (SendGrid/Resend)
- Supabase real-time subscriptions
## Risks
- HIGH: Email deliverability (SPF/DKIM required)
- MEDIUM: Performance with 1000+ users per market
- MEDIUM: Notification spam if markets resolve frequently
- LOW: Real-time subscription overhead
## Estimated Complexity: MEDIUM
- Backend: 4-6 hours
- Frontend: 3-4 hours
- Testing: 2-3 hours
- Total: 9-13 hours
**WAITING FOR CONFIRMATION**: Proceed with this plan? (yes/no/modify)
```
## Important Notes
**CRITICAL**: The planner agent will **NOT** write any code until you explicitly confirm the plan with "yes" or "proceed" or similar affirmative response.
If you want changes, respond with:
- "modify: [your changes]"
- "different approach: [alternative]"
- "skip phase 2 and do phase 3 first"
## Integration with Other Commands
After planning:
- Use `/tdd` to implement with test-driven development
- Use `/build-fix` if build errors occur
- Use `/code-review` to review completed implementation
## Related Agents
This command invokes the `planner` agent provided by ECC.
For manual installs, the source file lives at:
`agents/planner.md`

272
.agent/knowledge/everything_claude/commands/pm2.md Normal file
View File

@@ -0,0 +1,272 @@
# PM2 Init
Auto-analyze project and generate PM2 service commands.
**Command**: `$ARGUMENTS`
---
## Workflow
1. Check PM2 (install via `npm install -g pm2` if missing)
2. Scan project to identify services (frontend/backend/database)
3. Generate config files and individual command files
---
## Service Detection
| Type | Detection | Default Port |
|------|-----------|--------------|
| Vite | vite.config.* | 5173 |
| Next.js | next.config.* | 3000 |
| Nuxt | nuxt.config.* | 3000 |
| CRA | react-scripts in package.json | 3000 |
| Express/Node | server/backend/api directory + package.json | 3000 |
| FastAPI/Flask | requirements.txt / pyproject.toml | 8000 |
| Go | go.mod / main.go | 8080 |
**Port Detection Priority**: User specified > .env > config file > scripts args > default port
---
## Generated Files
```
project/
├── ecosystem.config.cjs # PM2 config
├── {backend}/start.cjs # Python wrapper (if applicable)
└── .claude/
├── commands/
│ ├── pm2-all.md # Start all + monit
│ ├── pm2-all-stop.md # Stop all
│ ├── pm2-all-restart.md # Restart all
│ ├── pm2-{port}.md # Start single + logs
│ ├── pm2-{port}-stop.md # Stop single
│ ├── pm2-{port}-restart.md # Restart single
│ ├── pm2-logs.md # View all logs
│ └── pm2-status.md # View status
└── scripts/
├── pm2-logs-{port}.ps1 # Single service logs
└── pm2-monit.ps1 # PM2 monitor
```
---
## Windows Configuration (IMPORTANT)
### ecosystem.config.cjs
**Must use `.cjs` extension**
```javascript
module.exports = {
apps: [
// Node.js (Vite/Next/Nuxt)
{
name: 'project-3000',
cwd: './packages/web',
script: 'node_modules/vite/bin/vite.js',
args: '--port 3000',
interpreter: 'C:/Program Files/nodejs/node.exe',
env: { NODE_ENV: 'development' }
},
// Python
{
name: 'project-8000',
cwd: './backend',
script: 'start.cjs',
interpreter: 'C:/Program Files/nodejs/node.exe',
env: { PYTHONUNBUFFERED: '1' }
}
]
}
```
**Framework script paths:**
| Framework | script | args |
|-----------|--------|------|
| Vite | `node_modules/vite/bin/vite.js` | `--port {port}` |
| Next.js | `node_modules/next/dist/bin/next` | `dev -p {port}` |
| Nuxt | `node_modules/nuxt/bin/nuxt.mjs` | `dev --port {port}` |
| Express | `src/index.js` or `server.js` | - |
### Python Wrapper Script (start.cjs)
```javascript
const { spawn } = require('child_process');
const proc = spawn('python', ['-m', 'uvicorn', 'app.main:app', '--host', '0.0.0.0', '--port', '8000', '--reload'], {
cwd: __dirname, stdio: 'inherit', windowsHide: true
});
proc.on('close', (code) => process.exit(code));
```
---
## Command File Templates (Minimal Content)
### pm2-all.md (Start all + monit)
````markdown
Start all services and open PM2 monitor.
```bash
cd "{PROJECT_ROOT}" && pm2 start ecosystem.config.cjs && start wt.exe -d "{PROJECT_ROOT}" pwsh -NoExit -c "pm2 monit"
```
````
### pm2-all-stop.md
````markdown
Stop all services.
```bash
cd "{PROJECT_ROOT}" && pm2 stop all
```
````
### pm2-all-restart.md
````markdown
Restart all services.
```bash
cd "{PROJECT_ROOT}" && pm2 restart all
```
````
### pm2-{port}.md (Start single + logs)
````markdown
Start {name} ({port}) and open logs.
```bash
cd "{PROJECT_ROOT}" && pm2 start ecosystem.config.cjs --only {name} && start wt.exe -d "{PROJECT_ROOT}" pwsh -NoExit -c "pm2 logs {name}"
```
````
### pm2-{port}-stop.md
````markdown
Stop {name} ({port}).
```bash
cd "{PROJECT_ROOT}" && pm2 stop {name}
```
````
### pm2-{port}-restart.md
````markdown
Restart {name} ({port}).
```bash
cd "{PROJECT_ROOT}" && pm2 restart {name}
```
````
### pm2-logs.md
````markdown
View all PM2 logs.
```bash
cd "{PROJECT_ROOT}" && pm2 logs
```
````
### pm2-status.md
````markdown
View PM2 status.
```bash
cd "{PROJECT_ROOT}" && pm2 status
```
````
### PowerShell Scripts (pm2-logs-{port}.ps1)
```powershell
Set-Location "{PROJECT_ROOT}"
pm2 logs {name}
```
### PowerShell Scripts (pm2-monit.ps1)
```powershell
Set-Location "{PROJECT_ROOT}"
pm2 monit
```
---
## Key Rules
1. **Config file**: `ecosystem.config.cjs` (not .js)
2. **Node.js**: Specify bin path directly + interpreter
3. **Python**: Node.js wrapper script + `windowsHide: true`
4. **Open new window**: `start wt.exe -d "{path}" pwsh -NoExit -c "command"`
5. **Minimal content**: Each command file has only 1-2 lines description + bash block
6. **Direct execution**: No AI parsing needed, just run the bash command
---
## Execute
Based on `$ARGUMENTS`, execute init:
1. Scan project for services
2. Generate `ecosystem.config.cjs`
3. Generate `{backend}/start.cjs` for Python services (if applicable)
4. Generate command files in `.claude/commands/`
5. Generate script files in `.claude/scripts/`
6. **Update project CLAUDE.md** with PM2 info (see below)
7. **Display completion summary** with terminal commands
---
## Post-Init: Update CLAUDE.md
After generating files, append PM2 section to project's `CLAUDE.md` (create if not exists):
````markdown
## PM2 Services
| Port | Name | Type |
|------|------|------|
| {port} | {name} | {type} |
**Terminal Commands:**
```bash
pm2 start ecosystem.config.cjs # First time
pm2 start all # After first time
pm2 stop all / pm2 restart all
pm2 start {name} / pm2 stop {name}
pm2 logs / pm2 status / pm2 monit
pm2 save # Save process list
pm2 resurrect # Restore saved list
```
````
**Rules for CLAUDE.md update:**
- If PM2 section exists, replace it
- If not exists, append to end
- Keep content minimal and essential
---
## Post-Init: Display Summary
After all files generated, output:
```
## PM2 Init Complete
**Services:**
| Port | Name | Type |
|------|------|------|
| {port} | {name} | {type} |
**Claude Commands:** /pm2-all, /pm2-all-stop, /pm2-{port}, /pm2-{port}-stop, /pm2-logs, /pm2-status
**Terminal Commands:**
## First time (with config file)
pm2 start ecosystem.config.cjs && pm2 save
## After first time (simplified)
pm2 start all # Start all
pm2 stop all # Stop all
pm2 restart all # Restart all
pm2 start {name} # Start single
pm2 stop {name} # Stop single
pm2 logs # View logs
pm2 monit # Monitor panel
pm2 resurrect # Restore saved processes
**Tip:** Run `pm2 save` after first start to enable simplified commands.
```

39
.agent/knowledge/everything_claude/commands/projects.md Normal file
View File

@@ -0,0 +1,39 @@
---
name: projects
description: List known projects and their instinct statistics
command: true
---
# Projects Command
List project registry entries and per-project instinct/observation counts for continuous-learning-v2.
## Implementation
Run the instinct CLI using the plugin root path:
```bash
python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" projects
```
Or if `CLAUDE_PLUGIN_ROOT` is not set (manual installation):
```bash
python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py projects
```
## Usage
```bash
/projects
```
## What to Do
1. Read `~/.claude/homunculus/projects.json`
2. For each project, display:
- Project name, id, root, remote
- Personal and inherited instinct counts
- Observation event count
- Last seen timestamp
3. Also display global instinct totals

41
.agent/knowledge/everything_claude/commands/promote.md Normal file
View File

@@ -0,0 +1,41 @@
---
name: promote
description: Promote project-scoped instincts to global scope
command: true
---
# Promote Command
Promote instincts from project scope to global scope in continuous-learning-v2.
## Implementation
Run the instinct CLI using the plugin root path:
```bash
python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" promote [instinct-id] [--force] [--dry-run]
```
Or if `CLAUDE_PLUGIN_ROOT` is not set (manual installation):
```bash
python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py promote [instinct-id] [--force] [--dry-run]
```
## Usage
```bash
/promote # Auto-detect promotion candidates
/promote --dry-run # Preview auto-promotion candidates
/promote --force # Promote all qualified candidates without prompt
/promote grep-before-edit # Promote one specific instinct from current project
```
## What to Do
1. Detect current project
2. If `instinct-id` is provided, promote only that instinct (if present in current project)
3. Otherwise, find cross-project candidates that:
- Appear in at least 2 projects
- Meet confidence threshold
4. Write promoted instincts to `~/.claude/homunculus/instincts/personal/` with `scope: global`

38
.agent/knowledge/everything_claude/commands/prompt-optimize.md Normal file
View File

@@ -0,0 +1,38 @@
---
description: Analyze a draft prompt and output an optimized, ECC-enriched version ready to paste and run. Does NOT execute the task — outputs advisory analysis only.
---
# /prompt-optimize
Analyze and optimize the following prompt for maximum ECC leverage.
## Your Task
Apply the **prompt-optimizer** skill to the user's input below. Follow the 6-phase analysis pipeline:
0. **Project Detection** — Read CLAUDE.md, detect tech stack from project files (package.json, go.mod, pyproject.toml, etc.)
1. **Intent Detection** — Classify the task type (new feature, bug fix, refactor, research, testing, review, documentation, infrastructure, design)
2. **Scope Assessment** — Evaluate complexity (TRIVIAL / LOW / MEDIUM / HIGH / EPIC), using codebase size as signal if detected
3. **ECC Component Matching** — Map to specific skills, commands, agents, and model tier
4. **Missing Context Detection** — Identify gaps. If 3+ critical items missing, ask the user to clarify before generating
5. **Workflow & Model** — Determine lifecycle position, recommend model tier, and split into multiple prompts if HIGH/EPIC
## Output Requirements
- Present diagnosis, recommended ECC components, and an optimized prompt using the Output Format from the prompt-optimizer skill
- Provide both **Full Version** (detailed) and **Quick Version** (compact, varied by intent type)
- Respond in the same language as the user's input
- The optimized prompt must be complete and ready to copy-paste into a new session
- End with a footer offering adjustment or a clear next step for starting a separate execution request
## CRITICAL
Do NOT execute the user's task. Output ONLY the analysis and optimized prompt.
If the user asks for direct execution, explain that `/prompt-optimize` only produces advisory output and tell them to start a normal task request instead.
Note: `blueprint` is a **skill**, not a slash command. Write "Use the blueprint skill"
instead of presenting it as a `/...` command.
## User Input
$ARGUMENTS

31
.agent/knowledge/everything_claude/commands/prune.md Normal file
View File

@@ -0,0 +1,31 @@
---
name: prune
description: Delete pending instincts older than 30 days that were never promoted
command: true
---
# Prune Pending Instincts
Remove expired pending instincts that were auto-generated but never reviewed or promoted.
## Implementation
Run the instinct CLI using the plugin root path:
```bash
python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" prune
```
Or if `CLAUDE_PLUGIN_ROOT` is not set (manual installation):
```bash
python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py prune
```
## Usage
```
/prune # Delete instincts older than 30 days
/prune --max-age 60 # Custom age threshold (days)
/prune --dry-run # Preview without deleting
```

297
.agent/knowledge/everything_claude/commands/python-review.md Normal file
View File

@@ -0,0 +1,297 @@
---
description: Comprehensive Python code review for PEP 8 compliance, type hints, security, and Pythonic idioms. Invokes the python-reviewer agent.
---
# Python Code Review
This command invokes the **python-reviewer** agent for comprehensive Python-specific code review.
## What This Command Does
1. **Identify Python Changes**: Find modified `.py` files via `git diff`
2. **Run Static Analysis**: Execute `ruff`, `mypy`, `pylint`, `black --check`
3. **Security Scan**: Check for SQL injection, command injection, unsafe deserialization
4. **Type Safety Review**: Analyze type hints and mypy errors
5. **Pythonic Code Check**: Verify code follows PEP 8 and Python best practices
6. **Generate Report**: Categorize issues by severity
## When to Use
Use `/python-review` when:
- After writing or modifying Python code
- Before committing Python changes
- Reviewing pull requests with Python code
- Onboarding to a new Python codebase
- Learning Pythonic patterns and idioms
## Review Categories
### CRITICAL (Must Fix)
- SQL/Command injection vulnerabilities
- Unsafe eval/exec usage
- Pickle unsafe deserialization
- Hardcoded credentials
- YAML unsafe load
- Bare except clauses hiding errors
### HIGH (Should Fix)
- Missing type hints on public functions
- Mutable default arguments
- Swallowing exceptions silently
- Not using context managers for resources
- C-style looping instead of comprehensions
- Using type() instead of isinstance()
- Race conditions without locks
### MEDIUM (Consider)
- PEP 8 formatting violations
- Missing docstrings on public functions
- Print statements instead of logging
- Inefficient string operations
- Magic numbers without named constants
- Not using f-strings for formatting
- Unnecessary list creation
## Automated Checks Run
```bash
# Type checking
mypy .
# Linting and formatting
ruff check .
black --check .
isort --check-only .
# Security scanning
bandit -r .
# Dependency audit
pip-audit
safety check
# Testing
pytest --cov=app --cov-report=term-missing
```
## Example Usage
```text
User: /python-review
Agent:
# Python Code Review Report
## Files Reviewed
- app/routes/user.py (modified)
- app/services/auth.py (modified)
## Static Analysis Results
✓ ruff: No issues
✓ mypy: No errors
⚠️ black: 2 files need reformatting
✓ bandit: No security issues
## Issues Found
[CRITICAL] SQL Injection vulnerability
File: app/routes/user.py:42
Issue: User input directly interpolated into SQL query
```python
query = f"SELECT * FROM users WHERE id = {user_id}" # Bad
```
Fix: Use parameterized query
```python
query = "SELECT * FROM users WHERE id = %s" # Good
cursor.execute(query, (user_id,))
```
[HIGH] Mutable default argument
File: app/services/auth.py:18
Issue: Mutable default argument causes shared state
```python
def process_items(items=[]): # Bad
items.append("new")
return items
```
Fix: Use None as default
```python
def process_items(items=None): # Good
if items is None:
items = []
items.append("new")
return items
```
[MEDIUM] Missing type hints
File: app/services/auth.py:25
Issue: Public function without type annotations
```python
def get_user(user_id): # Bad
return db.find(user_id)
```
Fix: Add type hints
```python
def get_user(user_id: str) -> Optional[User]: # Good
return db.find(user_id)
```
[MEDIUM] Not using context manager
File: app/routes/user.py:55
Issue: File not closed on exception
```python
f = open("config.json") # Bad
data = f.read()
f.close()
```
Fix: Use context manager
```python
with open("config.json") as f: # Good
data = f.read()
```
## Summary
- CRITICAL: 1
- HIGH: 1
- MEDIUM: 2
Recommendation: ❌ Block merge until CRITICAL issue is fixed
## Formatting Required
Run: `black app/routes/user.py app/services/auth.py`
```
## Approval Criteria
| Status | Condition |
|--------|-----------|
| ✅ Approve | No CRITICAL or HIGH issues |
| ⚠️ Warning | Only MEDIUM issues (merge with caution) |
| ❌ Block | CRITICAL or HIGH issues found |
## Integration with Other Commands
- Use `/tdd` first to ensure tests pass
- Use `/code-review` for non-Python specific concerns
- Use `/python-review` before committing
- Use `/build-fix` if static analysis tools fail
## Framework-Specific Reviews
### Django Projects
The reviewer checks for:
- N+1 query issues (use `select_related` and `prefetch_related`)
- Missing migrations for model changes
- Raw SQL usage when ORM could work
- Missing `transaction.atomic()` for multi-step operations
### FastAPI Projects
The reviewer checks for:
- CORS misconfiguration
- Pydantic models for request validation
- Response models correctness
- Proper async/await usage
- Dependency injection patterns
### Flask Projects
The reviewer checks for:
- Context management (app context, request context)
- Proper error handling
- Blueprint organization
- Configuration management
## Related
- Agent: `agents/python-reviewer.md`
- Skills: `skills/python-patterns/`, `skills/python-testing/`
## Common Fixes
### Add Type Hints
```python
# Before
def calculate(x, y):
return x + y
# After
from typing import Union
def calculate(x: Union[int, float], y: Union[int, float]) -> Union[int, float]:
return x + y
```
### Use Context Managers
```python
# Before
f = open("file.txt")
data = f.read()
f.close()
# After
with open("file.txt") as f:
data = f.read()
```
### Use List Comprehensions
```python
# Before
result = []
for item in items:
if item.active:
result.append(item.name)
# After
result = [item.name for item in items if item.active]
```
### Fix Mutable Defaults
```python
# Before
def append(value, items=[]):
items.append(value)
return items
# After
def append(value, items=None):
if items is None:
items = []
items.append(value)
return items
```
### Use f-strings (Python 3.6+)
```python
# Before
name = "Alice"
greeting = "Hello, " + name + "!"
greeting2 = "Hello, {}".format(name)
# After
greeting = f"Hello, {name}!"
```
### Fix String Concatenation in Loops
```python
# Before
result = ""
for item in items:
result += str(item)
# After
result = "".join(str(item) for item in items)
```
## Python Version Compatibility
The reviewer notes when code uses features from newer Python versions:
| Feature | Minimum Python |
|---------|----------------|
| Type hints | 3.5+ |
| f-strings | 3.6+ |
| Walrus operator (`:=`) | 3.8+ |
| Position-only parameters | 3.8+ |
| Match statements | 3.10+ |
| Type unions (&#96;x &#124; None&#96;) | 3.10+ |
Ensure your project's `pyproject.toml` or `setup.py` specifies the correct minimum Python version.

29
.agent/knowledge/everything_claude/commands/quality-gate.md Normal file
View File

@@ -0,0 +1,29 @@
# Quality Gate Command
Run the ECC quality pipeline on demand for a file or project scope.
## Usage
`/quality-gate [path|.] [--fix] [--strict]`
- default target: current directory (`.`)
- `--fix`: allow auto-format/fix where configured
- `--strict`: fail on warnings where supported
## Pipeline
1. Detect language/tooling for target.
2. Run formatter checks.
3. Run lint/type checks when available.
4. Produce a concise remediation list.
## Notes
This command mirrors hook behavior but is operator-invoked.
## Arguments
$ARGUMENTS:
- `[path|.]` optional target path
- `--fix` optional
- `--strict` optional

80
.agent/knowledge/everything_claude/commands/refactor-clean.md Normal file
View File

@@ -0,0 +1,80 @@
# Refactor Clean
Safely identify and remove dead code with test verification at every step.
## Step 1: Detect Dead Code
Run analysis tools based on project type:
| Tool | What It Finds | Command |
|------|--------------|---------|
| knip | Unused exports, files, dependencies | `npx knip` |
| depcheck | Unused npm dependencies | `npx depcheck` |
| ts-prune | Unused TypeScript exports | `npx ts-prune` |
| vulture | Unused Python code | `vulture src/` |
| deadcode | Unused Go code | `deadcode ./...` |
| cargo-udeps | Unused Rust dependencies | `cargo +nightly udeps` |
If no tool is available, use Grep to find exports with zero imports:
```
# Find exports, then check if they're imported anywhere
```
## Step 2: Categorize Findings
Sort findings into safety tiers:
| Tier | Examples | Action |
|------|----------|--------|
| **SAFE** | Unused utilities, test helpers, internal functions | Delete with confidence |
| **CAUTION** | Components, API routes, middleware | Verify no dynamic imports or external consumers |
| **DANGER** | Config files, entry points, type definitions | Investigate before touching |
## Step 3: Safe Deletion Loop
For each SAFE item:
1. **Run full test suite** — Establish baseline (all green)
2. **Delete the dead code** — Use Edit tool for surgical removal
3. **Re-run test suite** — Verify nothing broke
4. **If tests fail** — Immediately revert with `git checkout -- <file>` and skip this item
5. **If tests pass** — Move to next item
## Step 4: Handle CAUTION Items
Before deleting CAUTION items:
- Search for dynamic imports: `import()`, `require()`, `__import__`
- Search for string references: route names, component names in configs
- Check if exported from a public package API
- Verify no external consumers (check dependents if published)
## Step 5: Consolidate Duplicates
After removing dead code, look for:
- Near-duplicate functions (>80% similar) — merge into one
- Redundant type definitions — consolidate
- Wrapper functions that add no value — inline them
- Re-exports that serve no purpose — remove indirection
## Step 6: Summary
Report results:
```
Dead Code Cleanup
──────────────────────────────
Deleted: 12 unused functions
3 unused files
5 unused dependencies
Skipped: 2 items (tests failed)
Saved: ~450 lines removed
──────────────────────────────
All tests passing ✅
```
## Rules
- **Never delete without running tests first**
- **One deletion at a time** — Atomic changes make rollback easy
- **Skip if uncertain** — Better to keep dead code than break production
- **Don't refactor while cleaning** — Separate concerns (clean first, refactor later)

156
.agent/knowledge/everything_claude/commands/resume-session.md Normal file
View File

@@ -0,0 +1,156 @@
---
description: Load the most recent session file from ~/.claude/session-data/ and resume work with full context from where the last session ended.
---
# Resume Session Command
Load the last saved session state and orient fully before doing any work.
This command is the counterpart to `/save-session`.
## When to Use
- Starting a new session to continue work from a previous day
- After starting a fresh session due to context limits
- When handing off a session file from another source (just provide the file path)
- Any time you have a session file and want Claude to fully absorb it before proceeding
## Usage
```
/resume-session # loads most recent file in ~/.claude/session-data/
/resume-session 2024-01-15 # loads most recent session for that date
/resume-session ~/.claude/session-data/2024-01-15-abc123de-session.tmp # loads a current short-id session file
/resume-session ~/.claude/sessions/2024-01-15-session.tmp # loads a specific legacy-format file
```
## Process
### Step 1: Find the session file
If no argument provided:
1. Check `~/.claude/session-data/`
2. Pick the most recently modified `*-session.tmp` file
3. If the folder does not exist or has no matching files, tell the user:
```
No session files found in ~/.claude/session-data/
Run /save-session at the end of a session to create one.
```
Then stop.
If an argument is provided:
- If it looks like a date (`YYYY-MM-DD`), search `~/.claude/session-data/` first, then the legacy
`~/.claude/sessions/`, for files matching `YYYY-MM-DD-session.tmp` (legacy format) or
`YYYY-MM-DD-<shortid>-session.tmp` (current format)
and load the most recently modified variant for that date
- If it looks like a file path, read that file directly
- If not found, report clearly and stop
### Step 2: Read the entire session file
Read the complete file. Do not summarize yet.
### Step 3: Confirm understanding
Respond with a structured briefing in this exact format:
```
SESSION LOADED: [actual resolved path to the file]
════════════════════════════════════════════════
PROJECT: [project name / topic from file]
WHAT WE'RE BUILDING:
[2-3 sentence summary in your own words]
CURRENT STATE:
✅ Working: [count] items confirmed
🔄 In Progress: [list files that are in progress]
🗒️ Not Started: [list planned but untouched]
WHAT NOT TO RETRY:
[list every failed approach with its reason — this is critical]
OPEN QUESTIONS / BLOCKERS:
[list any blockers or unanswered questions]
NEXT STEP:
[exact next step if defined in the file]
[if not defined: "No next step defined — recommend reviewing 'What Has NOT Been Tried Yet' together before starting"]
════════════════════════════════════════════════
Ready to continue. What would you like to do?
```
### Step 4: Wait for the user
Do NOT start working automatically. Do NOT touch any files. Wait for the user to say what to do next.
If the next step is clearly defined in the session file and the user says "continue" or "yes" or similar — proceed with that exact next step.
If no next step is defined — ask the user where to start, and optionally suggest an approach from the "What Has NOT Been Tried Yet" section.
---
## Edge Cases
**Multiple sessions for the same date** (`2024-01-15-session.tmp`, `2024-01-15-abc123de-session.tmp`):
Load the most recently modified matching file for that date, regardless of whether it uses the legacy no-id format or the current short-id format.
**Session file references files that no longer exist:**
Note this during the briefing — "⚠️ `path/to/file.ts` referenced in session but not found on disk."
**Session file is from more than 7 days ago:**
Note the gap — "⚠️ This session is from N days ago (threshold: 7 days). Things may have changed." — then proceed normally.
**User provides a file path directly (e.g., forwarded from a teammate):**
Read it and follow the same briefing process — the format is the same regardless of source.
**Session file is empty or malformed:**
Report: "Session file found but appears empty or unreadable. You may need to create a new one with /save-session."
---
## Example Output
```
SESSION LOADED: /Users/you/.claude/session-data/2024-01-15-abc123de-session.tmp
════════════════════════════════════════════════
PROJECT: my-app — JWT Authentication
WHAT WE'RE BUILDING:
User authentication with JWT tokens stored in httpOnly cookies.
Register and login endpoints are partially done. Route protection
via middleware hasn't been started yet.
CURRENT STATE:
✅ Working: 3 items (register endpoint, JWT generation, password hashing)
🔄 In Progress: app/api/auth/login/route.ts (token works, cookie not set yet)
🗒️ Not Started: middleware.ts, app/login/page.tsx
WHAT NOT TO RETRY:
❌ Next-Auth — conflicts with custom Prisma adapter, threw adapter error on every request
❌ localStorage for JWT — causes SSR hydration mismatch, incompatible with Next.js
OPEN QUESTIONS / BLOCKERS:
- Does cookies().set() work inside a Route Handler or only Server Actions?
NEXT STEP:
In app/api/auth/login/route.ts — set the JWT as an httpOnly cookie using
cookies().set('token', jwt, { httpOnly: true, secure: true, sameSite: 'strict' })
then test with Postman for a Set-Cookie header in the response.
════════════════════════════════════════════════
Ready to continue. What would you like to do?
```
---
## Notes
- Never modify the session file when loading it — it's a read-only historical record
- The briefing format is fixed — do not skip sections even if they are empty
- "What Not To Retry" must always be shown, even if it just says "None" — it's too important to miss
- After resuming, the user may want to run `/save-session` again at the end of the new session to create a new dated file

11
.agent/knowledge/everything_claude/commands/rules-distill.md Normal file
View File

@@ -0,0 +1,11 @@
---
description: "Scan skills to extract cross-cutting principles and distill them into rules"
---
# /rules-distill — Distill Principles from Skills into Rules
Scan installed skills, extract cross-cutting principles, and distill them into rules.
## Process
Follow the full workflow defined in the `rules-distill` skill.

187
.agent/knowledge/everything_claude/commands/rust-build.md Normal file
View File

@@ -0,0 +1,187 @@
---
description: Fix Rust build errors, borrow checker issues, and dependency problems incrementally. Invokes the rust-build-resolver agent for minimal, surgical fixes.
---
# Rust Build and Fix
This command invokes the **rust-build-resolver** agent to incrementally fix Rust build errors with minimal changes.
## What This Command Does
1. **Run Diagnostics**: Execute `cargo check`, `cargo clippy`, `cargo fmt --check`
2. **Parse Errors**: Identify error codes and affected files
3. **Fix Incrementally**: One error at a time
4. **Verify Each Fix**: Re-run `cargo check` after each change
5. **Report Summary**: Show what was fixed and what remains
## When to Use
Use `/rust-build` when:
- `cargo build` or `cargo check` fails with errors
- `cargo clippy` reports warnings
- Borrow checker or lifetime errors block compilation
- Cargo dependency resolution fails
- After pulling changes that break the build
## Diagnostic Commands Run
```bash
# Primary build check
cargo check 2>&1
# Lints and suggestions
cargo clippy -- -D warnings 2>&1
# Formatting check
cargo fmt --check 2>&1
# Dependency issues
cargo tree --duplicates
# Security audit (if available)
if command -v cargo-audit >/dev/null; then cargo audit; else echo "cargo-audit not installed"; fi
```
## Example Session
````text
User: /rust-build
Agent:
# Rust Build Resolution
## Initial Diagnostics
```bash
$ cargo check
error[E0502]: cannot borrow `map` as mutable because it is also borrowed as immutable
--> src/service/cache.rs:25:5
error[E0308]: mismatched types
--> src/handler/api.rs:42:12
error[E0425]: cannot find value `db` in this scope
--> src/handler/api.rs:58:9
```
Errors found: 3
## Fix 1: Borrow Checker Error
File: src/service/cache.rs:25
Error: E0502 — cannot borrow `map` as mutable because also borrowed as immutable
Cause: Immutable borrow still active during mutable insert
```rust
// Changed: restructured to end immutable borrow before mutable access
if !map.contains_key("key") {
map.insert("key".into(), default);
}
```
```bash
$ cargo check
# 2 errors remaining
```
## Fix 2: Type Mismatch
File: src/handler/api.rs:42
Error: E0308 — mismatched types: expected `usize`, found `&str`
```rust
// Changed
let count = params.get("count");
// To
let count: usize = params.get("count")
.and_then(|s| s.parse().ok())
.unwrap_or(0);
```
```bash
$ cargo check
# 1 error remaining
```
## Fix 3: Unresolved Name
File: src/handler/api.rs:58
Error: E0425 — cannot find value `db` in this scope
Cause: Missing import
```rust
// Added
use crate::db;
```
```bash
$ cargo check
# Build successful!
```
## Final Verification
```bash
$ cargo clippy -- -D warnings
# No warnings
$ cargo test
running 6 tests
test service::cache::tests::test_insert ... ok
test service::cache::tests::test_get ... ok
test handler::api::tests::test_parse_count ... ok
test handler::api::tests::test_missing_count ... ok
test handler::api::tests::test_db_import ... ok
test handler::api::tests::test_response ... ok
test result: ok. 6 passed; 0 failed; 0 ignored
```
## Summary
| Metric | Count |
|--------|-------|
| Build errors fixed | 3 |
| Clippy warnings fixed | 0 |
| Files modified | 2 |
| Remaining issues | 0 |
Build Status: SUCCESS
````
## Common Errors Fixed
| Error | Typical Fix |
|-------|-------------|
| `cannot borrow as mutable` | Restructure to end immutable borrow first; clone only if justified |
| `does not live long enough` | Use owned type or add lifetime annotation |
| `cannot move out of` | Restructure to take ownership; clone only as last resort |
| `mismatched types` | Add `.into()`, `as`, or explicit conversion |
| `trait X not implemented` | Add `#[derive(Trait)]` or implement manually |
| `unresolved import` | Add to Cargo.toml or fix `use` path |
| `cannot find value` | Add import or fix path |
## Fix Strategy
1. **Build errors first** - Code must compile
2. **Clippy warnings second** - Fix suspicious constructs
3. **Formatting third** - `cargo fmt` compliance
4. **One fix at a time** - Verify each change
5. **Minimal changes** - Don't refactor, just fix
## Stop Conditions
The agent will stop and report if:
- Same error persists after 3 attempts
- Fix introduces more errors
- Requires architectural changes
- Borrow checker error requires redesigning data ownership
## Related Commands
- `/rust-test` - Run tests after build succeeds
- `/rust-review` - Review code quality
- `/verify` - Full verification loop
## Related
- Agent: `agents/rust-build-resolver.md`
- Skill: `skills/rust-patterns/`

142
.agent/knowledge/everything_claude/commands/rust-review.md Normal file
View File

@@ -0,0 +1,142 @@
---
description: Comprehensive Rust code review for ownership, lifetimes, error handling, unsafe usage, and idiomatic patterns. Invokes the rust-reviewer agent.
---
# Rust Code Review
This command invokes the **rust-reviewer** agent for comprehensive Rust-specific code review.
## What This Command Does
1. **Verify Automated Checks**: Run `cargo check`, `cargo clippy -- -D warnings`, `cargo fmt --check`, and `cargo test` — stop if any fail
2. **Identify Rust Changes**: Find modified `.rs` files via `git diff HEAD~1` (or `git diff main...HEAD` for PRs)
3. **Run Security Audit**: Execute `cargo audit` if available
4. **Security Scan**: Check for unsafe usage, command injection, hardcoded secrets
5. **Ownership Review**: Analyze unnecessary clones, lifetime issues, borrowing patterns
6. **Generate Report**: Categorize issues by severity
## When to Use
Use `/rust-review` when:
- After writing or modifying Rust code
- Before committing Rust changes
- Reviewing pull requests with Rust code
- Onboarding to a new Rust codebase
- Learning idiomatic Rust patterns
## Review Categories
### CRITICAL (Must Fix)
- Unchecked `unwrap()`/`expect()` in production code paths
- `unsafe` without `// SAFETY:` comment documenting invariants
- SQL injection via string interpolation in queries
- Command injection via unvalidated input in `std::process::Command`
- Hardcoded credentials
- Use-after-free via raw pointers
### HIGH (Should Fix)
- Unnecessary `.clone()` to satisfy borrow checker
- `String` parameter where `&str` or `impl AsRef<str>` suffices
- Blocking in async context (`std::thread::sleep`, `std::fs`)
- Missing `Send`/`Sync` bounds on shared types
- Wildcard `_ =>` match on business-critical enums
- Large functions (>50 lines)
### MEDIUM (Consider)
- Unnecessary allocation in hot paths
- Missing `with_capacity` when size is known
- Suppressed clippy warnings without justification
- Public API without `///` documentation
- Consider `#[must_use]` on non-`must_use` return types where ignoring values is likely a bug
## Automated Checks Run
```bash
# Build gate (must pass before review)
cargo check
# Lints and suggestions
cargo clippy -- -D warnings
# Formatting
cargo fmt --check
# Tests
cargo test
# Security audit (if available)
if command -v cargo-audit >/dev/null; then cargo audit; else echo "cargo-audit not installed"; fi
```
## Example Usage
````text
User: /rust-review
Agent:
# Rust Code Review Report
## Files Reviewed
- src/service/user.rs (modified)
- src/handler/api.rs (modified)
## Static Analysis Results
- Build: Successful
- Clippy: No warnings
- Formatting: Passed
- Tests: All passing
## Issues Found
[CRITICAL] Unchecked unwrap in Production Path
File: src/service/user.rs:28
Issue: Using `.unwrap()` on database query result
```rust
let user = db.find_by_id(id).unwrap(); // Panics on missing user
```
Fix: Propagate error with context
```rust
let user = db.find_by_id(id)
.context("failed to fetch user")?;
```
[HIGH] Unnecessary Clone
File: src/handler/api.rs:45
Issue: Cloning String to satisfy borrow checker
```rust
let name = user.name.clone();
process(&user, &name);
```
Fix: Restructure to avoid clone
```rust
let result = process_name(&user.name);
use_user(&user, result);
```
## Summary
- CRITICAL: 1
- HIGH: 1
- MEDIUM: 0
Recommendation: Block merge until CRITICAL issue is fixed
````
## Approval Criteria
| Status | Condition |
|--------|-----------|
| Approve | No CRITICAL or HIGH issues |
| Warning | Only MEDIUM issues (merge with caution) |
| Block | CRITICAL or HIGH issues found |
## Integration with Other Commands
- Use `/rust-test` first to ensure tests pass
- Use `/rust-build` if build errors occur
- Use `/rust-review` before committing
- Use `/code-review` for non-Rust-specific concerns
## Related
- Agent: `agents/rust-reviewer.md`
- Skills: `skills/rust-patterns/`, `skills/rust-testing/`

308
.agent/knowledge/everything_claude/commands/rust-test.md Normal file
View File

@@ -0,0 +1,308 @@
---
description: Enforce TDD workflow for Rust. Write tests first, then implement. Verify 80%+ coverage with cargo-llvm-cov.
---
# Rust TDD Command
This command enforces test-driven development methodology for Rust code using `#[test]`, rstest, proptest, and mockall.
## What This Command Does
1. **Define Types/Traits**: Scaffold function signatures with `todo!()`
2. **Write Tests**: Create comprehensive test module (RED)
3. **Run Tests**: Verify tests fail for the right reason
4. **Implement Code**: Write minimal code to pass (GREEN)
5. **Refactor**: Improve while keeping tests green
6. **Check Coverage**: Ensure 80%+ coverage with cargo-llvm-cov
## When to Use
Use `/rust-test` when:
- Implementing new Rust functions, methods, or traits
- Adding test coverage to existing Rust code
- Fixing bugs (write failing test first)
- Building critical business logic
- Learning TDD workflow in Rust
## TDD Cycle
```
RED -> Write failing test first
GREEN -> Implement minimal code to pass
REFACTOR -> Improve code, tests stay green
REPEAT -> Next test case
```
## Example Session
````text
User: /rust-test I need a function to validate user registration
Agent:
# TDD Session: Registration Validator
## Step 1: Define Interface
```rust
// src/validator.rs
pub struct RegistrationRequest {
pub name: String,
pub email: String,
pub password: String,
}
pub enum ValidationResult {
Valid,
Invalid(Vec<String>),
}
pub fn validate_registration(request: &RegistrationRequest) -> ValidationResult {
todo!()
}
```
## Step 2: Write Tests (RED)
```rust
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn valid_registration_returns_valid() {
let request = RegistrationRequest {
name: "Alice".into(),
email: "alice@example.com".into(),
password: "SecureP@ss1".into(),
};
assert!(matches!(validate_registration(&request), ValidationResult::Valid));
}
#[test]
fn blank_name_returns_invalid() {
let request = RegistrationRequest {
name: "".into(),
email: "alice@example.com".into(),
password: "SecureP@ss1".into(),
};
match validate_registration(&request) {
ValidationResult::Invalid(errors) => {
assert!(errors.contains(&"Name is required".to_string()));
}
ValidationResult::Valid => panic!("expected Invalid"),
}
}
#[test]
fn invalid_email_returns_invalid() {
let request = RegistrationRequest {
name: "Alice".into(),
email: "not-an-email".into(),
password: "SecureP@ss1".into(),
};
assert!(matches!(
validate_registration(&request),
ValidationResult::Invalid(_)
));
}
#[test]
fn short_password_returns_invalid() {
let request = RegistrationRequest {
name: "Alice".into(),
email: "alice@example.com".into(),
password: "short".into(),
};
assert!(matches!(
validate_registration(&request),
ValidationResult::Invalid(_)
));
}
}
```
## Step 3: Run Tests — Verify FAIL
```bash
$ cargo test
running 4 tests
test tests::valid_registration_returns_valid ... FAILED (not yet implemented)
test tests::blank_name_returns_invalid ... FAILED
test tests::invalid_email_returns_invalid ... FAILED
test tests::short_password_returns_invalid ... FAILED
```
Tests fail as expected (todo! panic).
## Step 4: Implement Minimal Code (GREEN)
```rust
pub fn validate_registration(request: &RegistrationRequest) -> ValidationResult {
let mut errors = Vec::new();
if request.name.trim().is_empty() {
errors.push("Name is required".into());
}
if !request.email.contains('@') {
errors.push("Invalid email format".into());
}
if request.password.len() < 8 {
errors.push("Password must be at least 8 characters".into());
}
if errors.is_empty() {
ValidationResult::Valid
} else {
ValidationResult::Invalid(errors)
}
}
```
## Step 5: Run Tests — Verify PASS
```bash
$ cargo test
running 4 tests
test tests::valid_registration_returns_valid ... ok
test tests::blank_name_returns_invalid ... ok
test tests::invalid_email_returns_invalid ... ok
test tests::short_password_returns_invalid ... ok
test result: ok. 4 passed; 0 failed
```
All tests passing!
## Step 6: Check Coverage
```bash
$ cargo llvm-cov
Coverage: 100.0% of lines
```
Coverage: 100%
## TDD Complete!
````
## Test Patterns
### Unit Tests
```rust
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn adds_two_numbers() {
assert_eq!(add(2, 3), 5);
}
#[test]
fn handles_error() -> Result<(), Box<dyn std::error::Error>> {
let result = parse_config(r#"port = 8080"#)?;
assert_eq!(result.port, 8080);
Ok(())
}
}
```
### Parameterized Tests with rstest
```rust
use rstest::{rstest, fixture};
#[rstest]
#[case("hello", 5)]
#[case("", 0)]
#[case("rust", 4)]
fn test_string_length(#[case] input: &str, #[case] expected: usize) {
assert_eq!(input.len(), expected);
}
```
### Async Tests
```rust
#[tokio::test]
async fn fetches_data_successfully() {
let client = TestClient::new().await;
let result = client.get("/data").await;
assert!(result.is_ok());
}
```
### Property-Based Tests
```rust
use proptest::prelude::*;
proptest! {
#[test]
fn encode_decode_roundtrip(input in ".*") {
let encoded = encode(&input);
let decoded = decode(&encoded).unwrap();
assert_eq!(input, decoded);
}
}
```
## Coverage Commands
```bash
# Summary report
cargo llvm-cov
# HTML report
cargo llvm-cov --html
# Fail if below threshold
cargo llvm-cov --fail-under-lines 80
# Run specific test
cargo test test_name
# Run with output
cargo test -- --nocapture
# Run without stopping on first failure
cargo test --no-fail-fast
```
## Coverage Targets
| Code Type | Target |
|-----------|--------|
| Critical business logic | 100% |
| Public API | 90%+ |
| General code | 80%+ |
| Generated / FFI bindings | Exclude |
## TDD Best Practices
**DO:**
- Write test FIRST, before any implementation
- Run tests after each change
- Use `assert_eq!` over `assert!` for better error messages
- Use `?` in tests that return `Result` for cleaner output
- Test behavior, not implementation
- Include edge cases (empty, boundary, error paths)
**DON'T:**
- Write implementation before tests
- Skip the RED phase
- Use `#[should_panic]` when `Result::is_err()` works
- Use `sleep()` in tests — use channels or `tokio::time::pause()`
- Mock everything — prefer integration tests when feasible
## Related Commands
- `/rust-build` - Fix build errors
- `/rust-review` - Review code after implementation
- `/verify` - Run full verification loop
## Related
- Skill: `skills/rust-testing/`
- Skill: `skills/rust-patterns/`

275
.agent/knowledge/everything_claude/commands/save-session.md Normal file
View File

@@ -0,0 +1,275 @@
---
description: Save current session state to a dated file in ~/.claude/session-data/ so work can be resumed in a future session with full context.
---
# Save Session Command
Capture everything that happened in this session — what was built, what worked, what failed, what's left — and write it to a dated file so the next session can pick up exactly where this one left off.
## When to Use
- End of a work session before closing Claude Code
- Before hitting context limits (run this first, then start a fresh session)
- After solving a complex problem you want to remember
- Any time you need to hand off context to a future session
## Process
### Step 1: Gather context
Before writing the file, collect:
- Read all files modified during this session (use git diff or recall from conversation)
- Review what was discussed, attempted, and decided
- Note any errors encountered and how they were resolved (or not)
- Check current test/build status if relevant
### Step 2: Create the sessions folder if it doesn't exist
Create the canonical sessions folder in the user's Claude home directory:
```bash
mkdir -p ~/.claude/session-data
```
### Step 3: Write the session file
Create `~/.claude/session-data/YYYY-MM-DD-<short-id>-session.tmp`, using today's actual date and a short-id that satisfies the rules enforced by `SESSION_FILENAME_REGEX` in `session-manager.js`:
- Compatibility characters: letters `a-z` / `A-Z`, digits `0-9`, hyphens `-`, underscores `_`
- Compatibility minimum length: 1 character
- Recommended style for new files: lowercase letters, digits, and hyphens with 8+ characters to avoid collisions
Valid examples: `abc123de`, `a1b2c3d4`, `frontend-worktree-1`, `ChezMoi_2`
Avoid for new files: `A`, `test_id1`, `ABC123de`
Full valid filename example: `2024-01-15-abc123de-session.tmp`
The legacy filename `YYYY-MM-DD-session.tmp` is still valid, but new session files should prefer the short-id form to avoid same-day collisions.
### Step 4: Populate the file with all sections below
Write every section honestly. Do not skip sections — write "Nothing yet" or "N/A" if a section genuinely has no content. An incomplete file is worse than an honest empty section.
### Step 5: Show the file to the user
After writing, display the full contents and ask:
```
Session saved to [actual resolved path to the session file]
Does this look accurate? Anything to correct or add before we close?
```
Wait for confirmation. Make edits if requested.
---
## Session File Format
```markdown
# Session: YYYY-MM-DD
**Started:** [approximate time if known]
**Last Updated:** [current time]
**Project:** [project name or path]
**Topic:** [one-line summary of what this session was about]
---
## What We Are Building
[1-3 paragraphs describing the feature, bug fix, or task. Include enough
context that someone with zero memory of this session can understand the goal.
Include: what it does, why it's needed, how it fits into the larger system.]
---
## What WORKED (with evidence)
[List only things that are confirmed working. For each item include WHY you
know it works — test passed, ran in browser, Postman returned 200, etc.
Without evidence, move it to "Not Tried Yet" instead.]
- **[thing that works]** — confirmed by: [specific evidence]
- **[thing that works]** — confirmed by: [specific evidence]
If nothing is confirmed working yet: "Nothing confirmed working yet — all approaches still in progress or untested."
---
## What Did NOT Work (and why)
[This is the most important section. List every approach tried that failed.
For each failure write the EXACT reason so the next session doesn't retry it.
Be specific: "threw X error because Y" is useful. "didn't work" is not.]
- **[approach tried]** — failed because: [exact reason / error message]
- **[approach tried]** — failed because: [exact reason / error message]
If nothing failed: "No failed approaches yet."
---
## What Has NOT Been Tried Yet
[Approaches that seem promising but haven't been attempted. Ideas from the
conversation. Alternative solutions worth exploring. Be specific enough that
the next session knows exactly what to try.]
- [approach / idea]
- [approach / idea]
If nothing is queued: "No specific untried approaches identified."
---
## Current State of Files
[Every file touched this session. Be precise about what state each file is in.]
| File | Status | Notes |
| ----------------- | -------------- | -------------------------- |
| `path/to/file.ts` | ✅ Complete | [what it does] |
| `path/to/file.ts` | 🔄 In Progress | [what's done, what's left] |
| `path/to/file.ts` | ❌ Broken | [what's wrong] |
| `path/to/file.ts` | 🗒️ Not Started | [planned but not touched] |
If no files were touched: "No files modified this session."
---
## Decisions Made
[Architecture choices, tradeoffs accepted, approaches chosen and why.
These prevent the next session from relitigating settled decisions.]
- **[decision]** — reason: [why this was chosen over alternatives]
If no significant decisions: "No major decisions made this session."
---
## Blockers & Open Questions
[Anything unresolved that the next session needs to address or investigate.
Questions that came up but weren't answered. External dependencies waiting on.]
- [blocker / open question]
If none: "No active blockers."
---
## Exact Next Step
[If known: The single most important thing to do when resuming. Be precise
enough that resuming requires zero thinking about where to start.]
[If not known: "Next step not determined — review 'What Has NOT Been Tried Yet'
and 'Blockers' sections to decide on direction before starting."]
---
## Environment & Setup Notes
[Only fill this if relevant — commands needed to run the project, env vars
required, services that need to be running, etc. Skip if standard setup.]
[If none: omit this section entirely.]
```
---
## Example Output
```markdown
# Session: 2024-01-15
**Started:** ~2pm
**Last Updated:** 5:30pm
**Project:** my-app
**Topic:** Building JWT authentication with httpOnly cookies
---
## What We Are Building
User authentication system for the Next.js app. Users register with email/password,
receive a JWT stored in an httpOnly cookie (not localStorage), and protected routes
check for a valid token via middleware. The goal is session persistence across browser
refreshes without exposing the token to JavaScript.
---
## What WORKED (with evidence)
- **`/api/auth/register` endpoint** — confirmed by: Postman POST returns 200 with user
object, row visible in Supabase dashboard, bcrypt hash stored correctly
- **JWT generation in `lib/auth.ts`** — confirmed by: unit test passes
(`npm test -- auth.test.ts`), decoded token at jwt.io shows correct payload
- **Password hashing** — confirmed by: `bcrypt.compare()` returns true in test
---
## What Did NOT Work (and why)
- **Next-Auth library** — failed because: conflicts with our custom Prisma adapter,
threw "Cannot use adapter with credentials provider in this configuration" on every
request. Not worth debugging — too opinionated for our setup.
- **Storing JWT in localStorage** — failed because: SSR renders happen before
localStorage is available, caused React hydration mismatch error on every page load.
This approach is fundamentally incompatible with Next.js SSR.
---
## What Has NOT Been Tried Yet
- Store JWT as httpOnly cookie in the login route response (most likely solution)
- Use `cookies()` from `next/headers` to read token in server components
- Write middleware.ts to protect routes by checking cookie existence
---
## Current State of Files
| File | Status | Notes |
| -------------------------------- | -------------- | ----------------------------------------------- |
| `app/api/auth/register/route.ts` | ✅ Complete | Works, tested |
| `app/api/auth/login/route.ts` | 🔄 In Progress | Token generates but not setting cookie yet |
| `lib/auth.ts` | ✅ Complete | JWT helpers, all tested |
| `middleware.ts` | 🗒️ Not Started | Route protection, needs cookie read logic first |
| `app/login/page.tsx` | 🗒️ Not Started | UI not started |
---
## Decisions Made
- **httpOnly cookie over localStorage** — reason: prevents XSS token theft, works with SSR
- **Custom auth over Next-Auth** — reason: Next-Auth conflicts with our Prisma setup, not worth the fight
---
## Blockers & Open Questions
- Does `cookies().set()` work inside a Route Handler or only in Server Actions? Need to verify.
---
## Exact Next Step
In `app/api/auth/login/route.ts`, after generating the JWT, set it as an httpOnly
cookie using `cookies().set('token', jwt, { httpOnly: true, secure: true, sameSite: 'strict' })`.
Then test with Postman — the response should include a `Set-Cookie` header.
```
---
## Notes
- Each session gets its own file — never append to a previous session's file
- The "What Did NOT Work" section is the most critical — future sessions will blindly retry failed approaches without it
- If the user asks to save mid-session (not just at the end), save what's known so far and mark in-progress items clearly
- The file is meant to be read by Claude at the start of the next session via `/resume-session`
- Use the canonical global session store: `~/.claude/session-data/`
- Prefer the short-id filename form (`YYYY-MM-DD-<short-id>-session.tmp`) for any new session file

333
.agent/knowledge/everything_claude/commands/sessions.md Normal file
View File

@@ -0,0 +1,333 @@
---
description: Manage Claude Code session history, aliases, and session metadata.
---
# Sessions Command
Manage Claude Code session history - list, load, alias, and edit sessions stored in `~/.claude/session-data/` with legacy reads from `~/.claude/sessions/`.
## Usage
`/sessions [list|load|alias|info|help] [options]`
## Actions
### List Sessions
Display all sessions with metadata, filtering, and pagination.
Use `/sessions info` when you need operator-surface context for a swarm: branch, worktree path, and session recency.
```bash
/sessions # List all sessions (default)
/sessions list # Same as above
/sessions list --limit 10 # Show 10 sessions
/sessions list --date 2026-02-01 # Filter by date
/sessions list --search abc # Search by session ID
```
**Script:**
```bash
node -e "
const sm = require((()=>{var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var p=require('path'),f=require('fs'),h=require('os').homedir(),d=p.join(h,'.claude'),q=p.join('scripts','lib','utils.js');if(f.existsSync(p.join(d,q)))return d;try{var b=p.join(d,'plugins','cache','everything-claude-code');for(var o of f.readdirSync(b))for(var v of f.readdirSync(p.join(b,o))){var c=p.join(b,o,v);if(f.existsSync(p.join(c,q)))return c}}catch(x){}return d})()+'/scripts/lib/session-manager');
const aa = require((()=>{var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var p=require('path'),f=require('fs'),h=require('os').homedir(),d=p.join(h,'.claude'),q=p.join('scripts','lib','utils.js');if(f.existsSync(p.join(d,q)))return d;try{var b=p.join(d,'plugins','cache','everything-claude-code');for(var o of f.readdirSync(b))for(var v of f.readdirSync(p.join(b,o))){var c=p.join(b,o,v);if(f.existsSync(p.join(c,q)))return c}}catch(x){}return d})()+'/scripts/lib/session-aliases');
const path = require('path');
const result = sm.getAllSessions({ limit: 20 });
const aliases = aa.listAliases();
const aliasMap = {};
for (const a of aliases) aliasMap[a.sessionPath] = a.name;
console.log('Sessions (showing ' + result.sessions.length + ' of ' + result.total + '):');
console.log('');
console.log('ID Date Time Branch Worktree Alias');
console.log('────────────────────────────────────────────────────────────────────');
for (const s of result.sessions) {
const alias = aliasMap[s.filename] || '';
const metadata = sm.parseSessionMetadata(sm.getSessionContent(s.sessionPath));
const id = s.shortId === 'no-id' ? '(none)' : s.shortId.slice(0, 8);
const time = s.modifiedTime.toTimeString().slice(0, 5);
const branch = (metadata.branch || '-').slice(0, 12);
const worktree = metadata.worktree ? path.basename(metadata.worktree).slice(0, 18) : '-';
console.log(id.padEnd(8) + ' ' + s.date + ' ' + time + ' ' + branch.padEnd(12) + ' ' + worktree.padEnd(18) + ' ' + alias);
}
"
```
### Load Session
Load and display a session's content (by ID or alias).
```bash
/sessions load <id|alias> # Load session
/sessions load 2026-02-01 # By date (for no-id sessions)
/sessions load a1b2c3d4 # By short ID
/sessions load my-alias # By alias name
```
**Script:**
```bash
node -e "
const sm = require((()=>{var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var p=require('path'),f=require('fs'),h=require('os').homedir(),d=p.join(h,'.claude'),q=p.join('scripts','lib','utils.js');if(f.existsSync(p.join(d,q)))return d;try{var b=p.join(d,'plugins','cache','everything-claude-code');for(var o of f.readdirSync(b))for(var v of f.readdirSync(p.join(b,o))){var c=p.join(b,o,v);if(f.existsSync(p.join(c,q)))return c}}catch(x){}return d})()+'/scripts/lib/session-manager');
const aa = require((()=>{var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var p=require('path'),f=require('fs'),h=require('os').homedir(),d=p.join(h,'.claude'),q=p.join('scripts','lib','utils.js');if(f.existsSync(p.join(d,q)))return d;try{var b=p.join(d,'plugins','cache','everything-claude-code');for(var o of f.readdirSync(b))for(var v of f.readdirSync(p.join(b,o))){var c=p.join(b,o,v);if(f.existsSync(p.join(c,q)))return c}}catch(x){}return d})()+'/scripts/lib/session-aliases');
const id = process.argv[1];
// First try to resolve as alias
const resolved = aa.resolveAlias(id);
const sessionId = resolved ? resolved.sessionPath : id;
const session = sm.getSessionById(sessionId, true);
if (!session) {
console.log('Session not found: ' + id);
process.exit(1);
}
const stats = sm.getSessionStats(session.sessionPath);
const size = sm.getSessionSize(session.sessionPath);
const aliases = aa.getAliasesForSession(session.filename);
console.log('Session: ' + session.filename);
console.log('Path: ' + session.sessionPath);
console.log('');
console.log('Statistics:');
console.log(' Lines: ' + stats.lineCount);
console.log(' Total items: ' + stats.totalItems);
console.log(' Completed: ' + stats.completedItems);
console.log(' In progress: ' + stats.inProgressItems);
console.log(' Size: ' + size);
console.log('');
if (aliases.length > 0) {
console.log('Aliases: ' + aliases.map(a => a.name).join(', '));
console.log('');
}
if (session.metadata.title) {
console.log('Title: ' + session.metadata.title);
console.log('');
}
if (session.metadata.started) {
console.log('Started: ' + session.metadata.started);
}
if (session.metadata.lastUpdated) {
console.log('Last Updated: ' + session.metadata.lastUpdated);
}
if (session.metadata.project) {
console.log('Project: ' + session.metadata.project);
}
if (session.metadata.branch) {
console.log('Branch: ' + session.metadata.branch);
}
if (session.metadata.worktree) {
console.log('Worktree: ' + session.metadata.worktree);
}
" "$ARGUMENTS"
```
### Create Alias
Create a memorable alias for a session.
```bash
/sessions alias <id> <name> # Create alias
/sessions alias 2026-02-01 today-work # Create alias named "today-work"
```
**Script:**
```bash
node -e "
const sm = require((()=>{var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var p=require('path'),f=require('fs'),h=require('os').homedir(),d=p.join(h,'.claude'),q=p.join('scripts','lib','utils.js');if(f.existsSync(p.join(d,q)))return d;try{var b=p.join(d,'plugins','cache','everything-claude-code');for(var o of f.readdirSync(b))for(var v of f.readdirSync(p.join(b,o))){var c=p.join(b,o,v);if(f.existsSync(p.join(c,q)))return c}}catch(x){}return d})()+'/scripts/lib/session-manager');
const aa = require((()=>{var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var p=require('path'),f=require('fs'),h=require('os').homedir(),d=p.join(h,'.claude'),q=p.join('scripts','lib','utils.js');if(f.existsSync(p.join(d,q)))return d;try{var b=p.join(d,'plugins','cache','everything-claude-code');for(var o of f.readdirSync(b))for(var v of f.readdirSync(p.join(b,o))){var c=p.join(b,o,v);if(f.existsSync(p.join(c,q)))return c}}catch(x){}return d})()+'/scripts/lib/session-aliases');
const sessionId = process.argv[1];
const aliasName = process.argv[2];
if (!sessionId || !aliasName) {
console.log('Usage: /sessions alias <id> <name>');
process.exit(1);
}
// Get session filename
const session = sm.getSessionById(sessionId);
if (!session) {
console.log('Session not found: ' + sessionId);
process.exit(1);
}
const result = aa.setAlias(aliasName, session.filename);
if (result.success) {
console.log('✓ Alias created: ' + aliasName + ' → ' + session.filename);
} else {
console.log('✗ Error: ' + result.error);
process.exit(1);
}
" "$ARGUMENTS"
```
### Remove Alias
Delete an existing alias.
```bash
/sessions alias --remove <name> # Remove alias
/sessions unalias <name> # Same as above
```
**Script:**
```bash
node -e "
const aa = require((()=>{var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var p=require('path'),f=require('fs'),h=require('os').homedir(),d=p.join(h,'.claude'),q=p.join('scripts','lib','utils.js');if(f.existsSync(p.join(d,q)))return d;try{var b=p.join(d,'plugins','cache','everything-claude-code');for(var o of f.readdirSync(b))for(var v of f.readdirSync(p.join(b,o))){var c=p.join(b,o,v);if(f.existsSync(p.join(c,q)))return c}}catch(x){}return d})()+'/scripts/lib/session-aliases');
const aliasName = process.argv[1];
if (!aliasName) {
console.log('Usage: /sessions alias --remove <name>');
process.exit(1);
}
const result = aa.deleteAlias(aliasName);
if (result.success) {
console.log('✓ Alias removed: ' + aliasName);
} else {
console.log('✗ Error: ' + result.error);
process.exit(1);
}
" "$ARGUMENTS"
```
### Session Info
Show detailed information about a session.
```bash
/sessions info <id|alias> # Show session details
```
**Script:**
```bash
node -e "
const sm = require((()=>{var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var p=require('path'),f=require('fs'),h=require('os').homedir(),d=p.join(h,'.claude'),q=p.join('scripts','lib','utils.js');if(f.existsSync(p.join(d,q)))return d;try{var b=p.join(d,'plugins','cache','everything-claude-code');for(var o of f.readdirSync(b))for(var v of f.readdirSync(p.join(b,o))){var c=p.join(b,o,v);if(f.existsSync(p.join(c,q)))return c}}catch(x){}return d})()+'/scripts/lib/session-manager');
const aa = require((()=>{var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var p=require('path'),f=require('fs'),h=require('os').homedir(),d=p.join(h,'.claude'),q=p.join('scripts','lib','utils.js');if(f.existsSync(p.join(d,q)))return d;try{var b=p.join(d,'plugins','cache','everything-claude-code');for(var o of f.readdirSync(b))for(var v of f.readdirSync(p.join(b,o))){var c=p.join(b,o,v);if(f.existsSync(p.join(c,q)))return c}}catch(x){}return d})()+'/scripts/lib/session-aliases');
const id = process.argv[1];
const resolved = aa.resolveAlias(id);
const sessionId = resolved ? resolved.sessionPath : id;
const session = sm.getSessionById(sessionId, true);
if (!session) {
console.log('Session not found: ' + id);
process.exit(1);
}
const stats = sm.getSessionStats(session.sessionPath);
const size = sm.getSessionSize(session.sessionPath);
const aliases = aa.getAliasesForSession(session.filename);
console.log('Session Information');
console.log('════════════════════');
console.log('ID: ' + (session.shortId === 'no-id' ? '(none)' : session.shortId));
console.log('Filename: ' + session.filename);
console.log('Date: ' + session.date);
console.log('Modified: ' + session.modifiedTime.toISOString().slice(0, 19).replace('T', ' '));
console.log('Project: ' + (session.metadata.project || '-'));
console.log('Branch: ' + (session.metadata.branch || '-'));
console.log('Worktree: ' + (session.metadata.worktree || '-'));
console.log('');
console.log('Content:');
console.log(' Lines: ' + stats.lineCount);
console.log(' Total items: ' + stats.totalItems);
console.log(' Completed: ' + stats.completedItems);
console.log(' In progress: ' + stats.inProgressItems);
console.log(' Size: ' + size);
if (aliases.length > 0) {
console.log('Aliases: ' + aliases.map(a => a.name).join(', '));
}
" "$ARGUMENTS"
```
### List Aliases
Show all session aliases.
```bash
/sessions aliases # List all aliases
```
**Script:**
```bash
node -e "
const aa = require((()=>{var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var p=require('path'),f=require('fs'),h=require('os').homedir(),d=p.join(h,'.claude'),q=p.join('scripts','lib','utils.js');if(f.existsSync(p.join(d,q)))return d;try{var b=p.join(d,'plugins','cache','everything-claude-code');for(var o of f.readdirSync(b))for(var v of f.readdirSync(p.join(b,o))){var c=p.join(b,o,v);if(f.existsSync(p.join(c,q)))return c}}catch(x){}return d})()+'/scripts/lib/session-aliases');
const aliases = aa.listAliases();
console.log('Session Aliases (' + aliases.length + '):');
console.log('');
if (aliases.length === 0) {
console.log('No aliases found.');
} else {
console.log('Name Session File Title');
console.log('─────────────────────────────────────────────────────────────');
for (const a of aliases) {
const name = a.name.padEnd(12);
const file = (a.sessionPath.length > 30 ? a.sessionPath.slice(0, 27) + '...' : a.sessionPath).padEnd(30);
const title = a.title || '';
console.log(name + ' ' + file + ' ' + title);
}
}
"
```
## Operator Notes
- Session files persist `Project`, `Branch`, and `Worktree` in the header so `/sessions info` can disambiguate parallel tmux/worktree runs.
- For command-center style monitoring, combine `/sessions info`, `git diff --stat`, and the cost metrics emitted by `scripts/hooks/cost-tracker.js`.
## Arguments
$ARGUMENTS:
- `list [options]` - List sessions
- `--limit <n>` - Max sessions to show (default: 50)
- `--date <YYYY-MM-DD>` - Filter by date
- `--search <pattern>` - Search in session ID
- `load <id|alias>` - Load session content
- `alias <id> <name>` - Create alias for session
- `alias --remove <name>` - Remove alias
- `unalias <name>` - Same as `--remove`
- `info <id|alias>` - Show session statistics
- `aliases` - List all aliases
- `help` - Show this help
## Examples
```bash
# List all sessions
/sessions list
# Create an alias for today's session
/sessions alias 2026-02-01 today
# Load session by alias
/sessions load today
# Show session info
/sessions info today
# Remove alias
/sessions alias --remove today
# List all aliases
/sessions aliases
```
## Notes
- Sessions are stored as markdown files in `~/.claude/session-data/` with legacy reads from `~/.claude/sessions/`
- Aliases are stored in `~/.claude/session-aliases.json`
- Session IDs can be shortened (first 4-8 characters usually unique enough)
- Use aliases for frequently referenced sessions

80
.agent/knowledge/everything_claude/commands/setup-pm.md Normal file
View File

@@ -0,0 +1,80 @@
---
description: Configure your preferred package manager (npm/pnpm/yarn/bun)
disable-model-invocation: true
---
# Package Manager Setup
Configure your preferred package manager for this project or globally.
## Usage
```bash
# Detect current package manager
node scripts/setup-package-manager.js --detect
# Set global preference
node scripts/setup-package-manager.js --global pnpm
# Set project preference
node scripts/setup-package-manager.js --project bun
# List available package managers
node scripts/setup-package-manager.js --list
```
## Detection Priority
When determining which package manager to use, the following order is checked:
1. **Environment variable**: `CLAUDE_PACKAGE_MANAGER`
2. **Project config**: `.claude/package-manager.json`
3. **package.json**: `packageManager` field
4. **Lock file**: Presence of package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lockb
5. **Global config**: `~/.claude/package-manager.json`
6. **Fallback**: First available package manager (pnpm > bun > yarn > npm)
## Configuration Files
### Global Configuration
```json
// ~/.claude/package-manager.json
{
"packageManager": "pnpm"
}
```
### Project Configuration
```json
// .claude/package-manager.json
{
"packageManager": "bun"
}
```
### package.json
```json
{
"packageManager": "pnpm@8.6.0"
}
```
## Environment Variable
Set `CLAUDE_PACKAGE_MANAGER` to override all other detection methods:
```bash
# Windows (PowerShell)
$env:CLAUDE_PACKAGE_MANAGER = "pnpm"
# macOS/Linux
export CLAUDE_PACKAGE_MANAGER=pnpm
```
## Run the Detection
To see current package manager detection results, run:
```bash
node scripts/setup-package-manager.js --detect
```

174
.agent/knowledge/everything_claude/commands/skill-create.md Normal file
View File

@@ -0,0 +1,174 @@
---
name: skill-create
description: Analyze local git history to extract coding patterns and generate SKILL.md files. Local version of the Skill Creator GitHub App.
allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"]
---
# /skill-create - Local Skill Generation
Analyze your repository's git history to extract coding patterns and generate SKILL.md files that teach Claude your team's practices.
## Usage
```bash
/skill-create # Analyze current repo
/skill-create --commits 100 # Analyze last 100 commits
/skill-create --output ./skills # Custom output directory
/skill-create --instincts # Also generate instincts for continuous-learning-v2
```
## What It Does
1. **Parses Git History** - Analyzes commits, file changes, and patterns
2. **Detects Patterns** - Identifies recurring workflows and conventions
3. **Generates SKILL.md** - Creates valid Claude Code skill files
4. **Optionally Creates Instincts** - For the continuous-learning-v2 system
## Analysis Steps
### Step 1: Gather Git Data
```bash
# Get recent commits with file changes
git log --oneline -n ${COMMITS:-200} --name-only --pretty=format:"%H|%s|%ad" --date=short
# Get commit frequency by file
git log --oneline -n 200 --name-only | grep -v "^$" | grep -v "^[a-f0-9]" | sort | uniq -c | sort -rn | head -20
# Get commit message patterns
git log --oneline -n 200 | cut -d' ' -f2- | head -50
```
### Step 2: Detect Patterns
Look for these pattern types:
| Pattern | Detection Method |
|---------|-----------------|
| **Commit conventions** | Regex on commit messages (feat:, fix:, chore:) |
| **File co-changes** | Files that always change together |
| **Workflow sequences** | Repeated file change patterns |
| **Architecture** | Folder structure and naming conventions |
| **Testing patterns** | Test file locations, naming, coverage |
### Step 3: Generate SKILL.md
Output format:
```markdown
---
name: {repo-name}-patterns
description: Coding patterns extracted from {repo-name}
version: 1.0.0
source: local-git-analysis
analyzed_commits: {count}
---
# {Repo Name} Patterns
## Commit Conventions
{detected commit message patterns}
## Code Architecture
{detected folder structure and organization}
## Workflows
{detected repeating file change patterns}
## Testing Patterns
{detected test conventions}
```
### Step 4: Generate Instincts (if --instincts)
For continuous-learning-v2 integration:
```yaml
---
id: {repo}-commit-convention
trigger: "when writing a commit message"
confidence: 0.8
domain: git
source: local-repo-analysis
---
# Use Conventional Commits
## Action
Prefix commits with: feat:, fix:, chore:, docs:, test:, refactor:
## Evidence
- Analyzed {n} commits
- {percentage}% follow conventional commit format
```
## Example Output
Running `/skill-create` on a TypeScript project might produce:
```markdown
---
name: my-app-patterns
description: Coding patterns from my-app repository
version: 1.0.0
source: local-git-analysis
analyzed_commits: 150
---
# My App Patterns
## Commit Conventions
This project uses **conventional commits**:
- `feat:` - New features
- `fix:` - Bug fixes
- `chore:` - Maintenance tasks
- `docs:` - Documentation updates
## Code Architecture
```
src/
├── components/ # React components (PascalCase.tsx)
├── hooks/ # Custom hooks (use*.ts)
├── utils/ # Utility functions
├── types/ # TypeScript type definitions
└── services/ # API and external services
```
## Workflows
### Adding a New Component
1. Create `src/components/ComponentName.tsx`
2. Add tests in `src/components/__tests__/ComponentName.test.tsx`
3. Export from `src/components/index.ts`
### Database Migration
1. Modify `src/db/schema.ts`
2. Run `pnpm db:generate`
3. Run `pnpm db:migrate`
## Testing Patterns
- Test files: `__tests__/` directories or `.test.ts` suffix
- Coverage target: 80%+
- Framework: Vitest
```
## GitHub App Integration
For advanced features (10k+ commits, team sharing, auto-PRs), use the [Skill Creator GitHub App](https://github.com/apps/skill-creator):
- Install: [github.com/apps/skill-creator](https://github.com/apps/skill-creator)
- Comment `/skill-creator analyze` on any issue
- Receives PR with generated skills
## Related Commands
- `/instinct-import` - Import generated instincts
- `/instinct-status` - View learned instincts
- `/evolve` - Cluster instincts into skills/agents
---
*Part of [Everything Claude Code](https://github.com/affaan-m/everything-claude-code)*

54
.agent/knowledge/everything_claude/commands/skill-health.md Normal file
View File

@@ -0,0 +1,54 @@
---
name: skill-health
description: Show skill portfolio health dashboard with charts and analytics
command: true
---
# Skill Health Dashboard
Shows a comprehensive health dashboard for all skills in the portfolio with success rate sparklines, failure pattern clustering, pending amendments, and version history.
## Implementation
Run the skill health CLI in dashboard mode:
```bash
ECC_ROOT="${CLAUDE_PLUGIN_ROOT:-$(node -e "var p=require('path'),f=require('fs'),h=require('os').homedir(),d=p.join(h,'.claude'),q=p.join('scripts','lib','utils.js');if(!f.existsSync(p.join(d,q))){try{var b=p.join(d,'plugins','cache','everything-claude-code');for(var o of f.readdirSync(b))for(var v of f.readdirSync(p.join(b,o))){var c=p.join(b,o,v);if(f.existsSync(p.join(c,q))){d=c;break}}}catch(x){}}console.log(d)")}"
node "$ECC_ROOT/scripts/skills-health.js" --dashboard
```
For a specific panel only:
```bash
ECC_ROOT="${CLAUDE_PLUGIN_ROOT:-$(node -e "var p=require('path'),f=require('fs'),h=require('os').homedir(),d=p.join(h,'.claude'),q=p.join('scripts','lib','utils.js');if(!f.existsSync(p.join(d,q))){try{var b=p.join(d,'plugins','cache','everything-claude-code');for(var o of f.readdirSync(b))for(var v of f.readdirSync(p.join(b,o))){var c=p.join(b,o,v);if(f.existsSync(p.join(c,q))){d=c;break}}}catch(x){}}console.log(d)")}"
node "$ECC_ROOT/scripts/skills-health.js" --dashboard --panel failures
```
For machine-readable output:
```bash
ECC_ROOT="${CLAUDE_PLUGIN_ROOT:-$(node -e "var p=require('path'),f=require('fs'),h=require('os').homedir(),d=p.join(h,'.claude'),q=p.join('scripts','lib','utils.js');if(!f.existsSync(p.join(d,q))){try{var b=p.join(d,'plugins','cache','everything-claude-code');for(var o of f.readdirSync(b))for(var v of f.readdirSync(p.join(b,o))){var c=p.join(b,o,v);if(f.existsSync(p.join(c,q))){d=c;break}}}catch(x){}}console.log(d)")}"
node "$ECC_ROOT/scripts/skills-health.js" --dashboard --json
```
## Usage
```
/skill-health # Full dashboard view
/skill-health --panel failures # Only failure clustering panel
/skill-health --json # Machine-readable JSON output
```
## What to Do
1. Run the skills-health.js script with --dashboard flag
2. Display the output to the user
3. If any skills are declining, highlight them and suggest running /evolve
4. If there are pending amendments, suggest reviewing them
## Panels
- **Success Rate (30d)** — Sparkline charts showing daily success rates per skill
- **Failure Patterns** — Clustered failure reasons with horizontal bar chart
- **Pending Amendments** — Amendment proposals awaiting review
- **Version History** — Timeline of version snapshots per skill

328
.agent/knowledge/everything_claude/commands/tdd.md Normal file
View File

@@ -0,0 +1,328 @@
---
description: Enforce test-driven development workflow. Scaffold interfaces, generate tests FIRST, then implement minimal code to pass. Ensure 80%+ coverage.
---
# TDD Command
This command invokes the **tdd-guide** agent to enforce test-driven development methodology.
## What This Command Does
1. **Scaffold Interfaces** - Define types/interfaces first
2. **Generate Tests First** - Write failing tests (RED)
3. **Implement Minimal Code** - Write just enough to pass (GREEN)
4. **Refactor** - Improve code while keeping tests green (REFACTOR)
5. **Verify Coverage** - Ensure 80%+ test coverage
## When to Use
Use `/tdd` when:
- Implementing new features
- Adding new functions/components
- Fixing bugs (write test that reproduces bug first)
- Refactoring existing code
- Building critical business logic
## How It Works
The tdd-guide agent will:
1. **Define interfaces** for inputs/outputs
2. **Write tests that will FAIL** (because code doesn't exist yet)
3. **Run tests** and verify they fail for the right reason
4. **Write minimal implementation** to make tests pass
5. **Run tests** and verify they pass
6. **Refactor** code while keeping tests green
7. **Check coverage** and add more tests if below 80%
## TDD Cycle
```
RED → GREEN → REFACTOR → REPEAT
RED: Write a failing test
GREEN: Write minimal code to pass
REFACTOR: Improve code, keep tests passing
REPEAT: Next feature/scenario
```
## Example Usage
```
User: /tdd I need a function to calculate market liquidity score
Agent (tdd-guide):
# TDD Session: Market Liquidity Score Calculator
## Step 1: Define Interface (SCAFFOLD)
```typescript
// lib/liquidity.ts
export interface MarketData {
totalVolume: number
bidAskSpread: number
activeTraders: number
lastTradeTime: Date
}
export function calculateLiquidityScore(market: MarketData): number {
// TODO: Implementation
throw new Error('Not implemented')
}
```
## Step 2: Write Failing Test (RED)
```typescript
// lib/liquidity.test.ts
import { calculateLiquidityScore } from './liquidity'
describe('calculateLiquidityScore', () => {
it('should return high score for liquid market', () => {
const market = {
totalVolume: 100000,
bidAskSpread: 0.01,
activeTraders: 500,
lastTradeTime: new Date()
}
const score = calculateLiquidityScore(market)
expect(score).toBeGreaterThan(80)
expect(score).toBeLessThanOrEqual(100)
})
it('should return low score for illiquid market', () => {
const market = {
totalVolume: 100,
bidAskSpread: 0.5,
activeTraders: 2,
lastTradeTime: new Date(Date.now() - 86400000) // 1 day ago
}
const score = calculateLiquidityScore(market)
expect(score).toBeLessThan(30)
expect(score).toBeGreaterThanOrEqual(0)
})
it('should handle edge case: zero volume', () => {
const market = {
totalVolume: 0,
bidAskSpread: 0,
activeTraders: 0,
lastTradeTime: new Date()
}
const score = calculateLiquidityScore(market)
expect(score).toBe(0)
})
})
```
## Step 3: Run Tests - Verify FAIL
```bash
npm test lib/liquidity.test.ts
FAIL lib/liquidity.test.ts
✕ should return high score for liquid market (2 ms)
Error: Not implemented
1 test failed, 0 passed
```
✅ Tests fail as expected. Ready to implement.
## Step 4: Implement Minimal Code (GREEN)
```typescript
// lib/liquidity.ts
export function calculateLiquidityScore(market: MarketData): number {
// Handle zero volume edge case
if (market.totalVolume === 0) {
return 0
}
// Calculate component scores (0-100 scale)
const volumeScore = Math.min(market.totalVolume / 1000, 100)
const spreadScore = Math.max(100 - (market.bidAskSpread * 1000), 0)
const traderScore = Math.min(market.activeTraders / 10, 100)
// Recent activity bonus
const hoursSinceLastTrade = (Date.now() - market.lastTradeTime.getTime()) / (1000 * 60 * 60)
const recencyScore = Math.max(100 - (hoursSinceLastTrade * 10), 0)
// Weighted average
const score = (
volumeScore * 0.4 +
spreadScore * 0.3 +
traderScore * 0.2 +
recencyScore * 0.1
)
return Math.min(Math.max(score, 0), 100) // Clamp to 0-100
}
```
## Step 5: Run Tests - Verify PASS
```bash
npm test lib/liquidity.test.ts
PASS lib/liquidity.test.ts
✓ should return high score for liquid market (3 ms)
✓ should return low score for illiquid market (2 ms)
✓ should handle edge case: zero volume (1 ms)
3 tests passed
```
✅ All tests passing!
## Step 6: Refactor (IMPROVE)
```typescript
// lib/liquidity.ts - Refactored with constants and better readability
const WEIGHTS = {
VOLUME: 0.4,
SPREAD: 0.3,
TRADERS: 0.2,
RECENCY: 0.1,
} as const
const SCALE_FACTORS = {
VOLUME: 1000,
SPREAD: 1000,
TRADERS: 10,
RECENCY_PENALTY: 10,
} as const
function clamp(value: number, min: number, max: number): number {
return Math.min(Math.max(value, min), max)
}
export function calculateLiquidityScore(market: MarketData): number {
if (market.totalVolume === 0) return 0
const volumeScore = Math.min(market.totalVolume / SCALE_FACTORS.VOLUME, 100)
const spreadScore = clamp(100 - (market.bidAskSpread * SCALE_FACTORS.SPREAD), 0, 100)
const traderScore = Math.min(market.activeTraders / SCALE_FACTORS.TRADERS, 100)
const hoursSinceLastTrade = (Date.now() - market.lastTradeTime.getTime()) / (1000 * 60 * 60)
const recencyScore = clamp(100 - (hoursSinceLastTrade * SCALE_FACTORS.RECENCY_PENALTY), 0, 100)
const weightedScore =
volumeScore * WEIGHTS.VOLUME +
spreadScore * WEIGHTS.SPREAD +
traderScore * WEIGHTS.TRADERS +
recencyScore * WEIGHTS.RECENCY
return clamp(weightedScore, 0, 100)
}
```
## Step 7: Verify Tests Still Pass
```bash
npm test lib/liquidity.test.ts
PASS lib/liquidity.test.ts
✓ should return high score for liquid market (3 ms)
✓ should return low score for illiquid market (2 ms)
✓ should handle edge case: zero volume (1 ms)
3 tests passed
```
✅ Refactoring complete, tests still passing!
## Step 8: Check Coverage
```bash
npm test -- --coverage lib/liquidity.test.ts
File | % Stmts | % Branch | % Funcs | % Lines
---------------|---------|----------|---------|--------
liquidity.ts | 100 | 100 | 100 | 100
Coverage: 100% ✅ (Target: 80%)
```
✅ TDD session complete!
```
## TDD Best Practices
**DO:**
- ✅ Write the test FIRST, before any implementation
- ✅ Run tests and verify they FAIL before implementing
- ✅ Write minimal code to make tests pass
- ✅ Refactor only after tests are green
- ✅ Add edge cases and error scenarios
- ✅ Aim for 80%+ coverage (100% for critical code)
**DON'T:**
- ❌ Write implementation before tests
- ❌ Skip running tests after each change
- ❌ Write too much code at once
- ❌ Ignore failing tests
- ❌ Test implementation details (test behavior)
- ❌ Mock everything (prefer integration tests)
## Test Types to Include
**Unit Tests** (Function-level):
- Happy path scenarios
- Edge cases (empty, null, max values)
- Error conditions
- Boundary values
**Integration Tests** (Component-level):
- API endpoints
- Database operations
- External service calls
- React components with hooks
**E2E Tests** (use `/e2e` command):
- Critical user flows
- Multi-step processes
- Full stack integration
## Coverage Requirements
- **80% minimum** for all code
- **100% required** for:
- Financial calculations
- Authentication logic
- Security-critical code
- Core business logic
## Important Notes
**MANDATORY**: Tests must be written BEFORE implementation. The TDD cycle is:
1. **RED** - Write failing test
2. **GREEN** - Implement to pass
3. **REFACTOR** - Improve code
Never skip the RED phase. Never write code before tests.
## Integration with Other Commands
- Use `/plan` first to understand what to build
- Use `/tdd` to implement with tests
- Use `/build-fix` if build errors occur
- Use `/code-review` to review implementation
- Use `/test-coverage` to verify coverage
## Related Agents
This command invokes the `tdd-guide` agent provided by ECC.
The related `tdd-workflow` skill is also bundled with ECC.
For manual installs, the source files live at:
- `agents/tdd-guide.md`
- `skills/tdd-workflow/SKILL.md`

69
.agent/knowledge/everything_claude/commands/test-coverage.md Normal file
View File

@@ -0,0 +1,69 @@
# Test Coverage
Analyze test coverage, identify gaps, and generate missing tests to reach 80%+ coverage.
## Step 1: Detect Test Framework
| Indicator | Coverage Command |
|-----------|-----------------|
| `jest.config.*` or `package.json` jest | `npx jest --coverage --coverageReporters=json-summary` |
| `vitest.config.*` | `npx vitest run --coverage` |
| `pytest.ini` / `pyproject.toml` pytest | `pytest --cov=src --cov-report=json` |
| `Cargo.toml` | `cargo llvm-cov --json` |
| `pom.xml` with JaCoCo | `mvn test jacoco:report` |
| `go.mod` | `go test -coverprofile=coverage.out ./...` |
## Step 2: Analyze Coverage Report
1. Run the coverage command
2. Parse the output (JSON summary or terminal output)
3. List files **below 80% coverage**, sorted worst-first
4. For each under-covered file, identify:
- Untested functions or methods
- Missing branch coverage (if/else, switch, error paths)
- Dead code that inflates the denominator
## Step 3: Generate Missing Tests
For each under-covered file, generate tests following this priority:
1. **Happy path** — Core functionality with valid inputs
2. **Error handling** — Invalid inputs, missing data, network failures
3. **Edge cases** — Empty arrays, null/undefined, boundary values (0, -1, MAX_INT)
4. **Branch coverage** — Each if/else, switch case, ternary
### Test Generation Rules
- Place tests adjacent to source: `foo.ts` → `foo.test.ts` (or project convention)
- Use existing test patterns from the project (import style, assertion library, mocking approach)
- Mock external dependencies (database, APIs, file system)
- Each test should be independent — no shared mutable state between tests
- Name tests descriptively: `test_create_user_with_duplicate_email_returns_409`
## Step 4: Verify
1. Run the full test suite — all tests must pass
2. Re-run coverage — verify improvement
3. If still below 80%, repeat Step 3 for remaining gaps
## Step 5: Report
Show before/after comparison:
```
Coverage Report
──────────────────────────────
File Before After
src/services/auth.ts 45% 88%
src/utils/validation.ts 32% 82%
──────────────────────────────
Overall: 67% 84% ✅
```
## Focus Areas
- Functions with complex branching (high cyclomatic complexity)
- Error handlers and catch blocks
- Utility functions used across the codebase
- API endpoint handlers (request → response flow)
- Edge cases: null, undefined, empty string, empty array, zero, negative numbers

72
.agent/knowledge/everything_claude/commands/update-codemaps.md Normal file
View File

@@ -0,0 +1,72 @@
# Update Codemaps
Analyze the codebase structure and generate token-lean architecture documentation.
## Step 1: Scan Project Structure
1. Identify the project type (monorepo, single app, library, microservice)
2. Find all source directories (src/, lib/, app/, packages/)
3. Map entry points (main.ts, index.ts, app.py, main.go, etc.)
## Step 2: Generate Codemaps
Create or update codemaps in `docs/CODEMAPS/` (or `.reports/codemaps/`):
| File | Contents |
|------|----------|
| `architecture.md` | High-level system diagram, service boundaries, data flow |
| `backend.md` | API routes, middleware chain, service → repository mapping |
| `frontend.md` | Page tree, component hierarchy, state management flow |
| `data.md` | Database tables, relationships, migration history |
| `dependencies.md` | External services, third-party integrations, shared libraries |
### Codemap Format
Each codemap should be token-lean — optimized for AI context consumption:
```markdown
# Backend Architecture
## Routes
POST /api/users → UserController.create → UserService.create → UserRepo.insert
GET /api/users/:id → UserController.get → UserService.findById → UserRepo.findById
## Key Files
src/services/user.ts (business logic, 120 lines)
src/repos/user.ts (database access, 80 lines)
## Dependencies
- PostgreSQL (primary data store)
- Redis (session cache, rate limiting)
- Stripe (payment processing)
```
## Step 3: Diff Detection
1. If previous codemaps exist, calculate the diff percentage
2. If changes > 30%, show the diff and request user approval before overwriting
3. If changes <= 30%, update in place
## Step 4: Add Metadata
Add a freshness header to each codemap:
```markdown
<!-- Generated: 2026-02-11 | Files scanned: 142 | Token estimate: ~800 -->
```
## Step 5: Save Analysis Report
Write a summary to `.reports/codemap-diff.txt`:
- Files added/removed/modified since last scan
- New dependencies detected
- Architecture changes (new routes, new services, etc.)
- Staleness warnings for docs not updated in 90+ days
## Tips
- Focus on **high-level structure**, not implementation details
- Prefer **file paths and function signatures** over full code blocks
- Keep each codemap under **1000 tokens** for efficient context loading
- Use ASCII diagrams for data flow instead of verbose descriptions
- Run after major feature additions or refactoring sessions

84
.agent/knowledge/everything_claude/commands/update-docs.md Normal file
View File

@@ -0,0 +1,84 @@
# Update Documentation
Sync documentation with the codebase, generating from source-of-truth files.
## Step 1: Identify Sources of Truth
| Source | Generates |
|--------|-----------|
| `package.json` scripts | Available commands reference |
| `.env.example` | Environment variable documentation |
| `openapi.yaml` / route files | API endpoint reference |
| Source code exports | Public API documentation |
| `Dockerfile` / `docker-compose.yml` | Infrastructure setup docs |
## Step 2: Generate Script Reference
1. Read `package.json` (or `Makefile`, `Cargo.toml`, `pyproject.toml`)
2. Extract all scripts/commands with their descriptions
3. Generate a reference table:
```markdown
| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server with hot reload |
| `npm run build` | Production build with type checking |
| `npm test` | Run test suite with coverage |
```
## Step 3: Generate Environment Documentation
1. Read `.env.example` (or `.env.template`, `.env.sample`)
2. Extract all variables with their purposes
3. Categorize as required vs optional
4. Document expected format and valid values
```markdown
| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `DATABASE_URL` | Yes | PostgreSQL connection string | `postgres://user:pass@host:5432/db` |
| `LOG_LEVEL` | No | Logging verbosity (default: info) | `debug`, `info`, `warn`, `error` |
```
## Step 4: Update Contributing Guide
Generate or update `docs/CONTRIBUTING.md` with:
- Development environment setup (prerequisites, install steps)
- Available scripts and their purposes
- Testing procedures (how to run, how to write new tests)
- Code style enforcement (linter, formatter, pre-commit hooks)
- PR submission checklist
## Step 5: Update Runbook
Generate or update `docs/RUNBOOK.md` with:
- Deployment procedures (step-by-step)
- Health check endpoints and monitoring
- Common issues and their fixes
- Rollback procedures
- Alerting and escalation paths
## Step 6: Staleness Check
1. Find documentation files not modified in 90+ days
2. Cross-reference with recent source code changes
3. Flag potentially outdated docs for manual review
## Step 7: Show Summary
```
Documentation Update
──────────────────────────────
Updated: docs/CONTRIBUTING.md (scripts table)
Updated: docs/ENV.md (3 new variables)
Flagged: docs/DEPLOY.md (142 days stale)
Skipped: docs/API.md (no changes detected)
──────────────────────────────
```
## Rules
- **Single source of truth**: Always generate from code, never manually edit generated sections
- **Preserve manual sections**: Only update generated sections; leave hand-written prose intact
- **Mark generated content**: Use `<!-- AUTO-GENERATED -->` markers around generated sections
- **Don't create docs unprompted**: Only create new doc files if the command explicitly requests it

59
.agent/knowledge/everything_claude/commands/verify.md Normal file
View File

@@ -0,0 +1,59 @@
# Verification Command
Run comprehensive verification on current codebase state.
## Instructions
Execute verification in this exact order:
1. **Build Check**
- Run the build command for this project
- If it fails, report errors and STOP
2. **Type Check**
- Run TypeScript/type checker
- Report all errors with file:line
3. **Lint Check**
- Run linter
- Report warnings and errors
4. **Test Suite**
- Run all tests
- Report pass/fail count
- Report coverage percentage
5. **Console.log Audit**
- Search for console.log in source files
- Report locations
6. **Git Status**
- Show uncommitted changes
- Show files modified since last commit
## Output
Produce a concise verification report:
```
VERIFICATION: [PASS/FAIL]
Build: [OK/FAIL]
Types: [OK/X errors]
Lint: [OK/X issues]
Tests: [X/Y passed, Z% coverage]
Secrets: [OK/X found]
Logs: [OK/X console.logs]
Ready for PR: [YES/NO]
```
If any critical issues, list them with fix suggestions.
## Arguments
$ARGUMENTS can be:
- `quick` - Only build + types
- `full` - All checks (default)
- `pre-commit` - Checks relevant for commits
- `pre-pr` - Full checks plus security scan