From 7379d6049a2a74b26a522238964ceae5c7ba3f51 Mon Sep 17 00:00:00 2001 From: Raymond Torino Date: Thu, 27 Aug 2026 15:26:38 +0800 Subject: [PATCH 1/2] feat(ce-work,ce-security-audit,ce-test-browser): re-port fork customizations onto upstream restructure Re-applies this fork's customizations on top of the upstream agent-native restructure (plugins/compound-engineering/* flattened to repo root; agents migrated to local persona/prompt assets under skills/*/references/). - ce-work: session-state resume check (Phase 0), per-task review pipeline (spec-compliance then code-quality reviewers), TDD guardrails, testing-anti-patterns, verification-discipline, and subagent-templates, woven into the new modular reference files (input-triage, execution-strategy, implementation-loop, shipping-workflow) to keep SKILL.md under the Codex 8000-byte budget. - Review agents converted from typed-agent dispatch to local prompt assets (skills/ce-work/references/agents/, skills/ce-security-audit/references/agents/) and dispatched as generic subagents, per the new architecture. - ce-security-audit: re-homed as a self-contained skill (duplicates the security-reviewer persona locally); registered in README + count guards. - ce-test-browser: single-spa and Element UI reference guides. - ce-debug: revert-and-verify-failure step in the fix loop. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 8 +- skills/ce-debug/references/fix.md | 2 +- skills/ce-security-audit/SKILL.md | 88 ++++++++++ .../references/agents/security-reviewer.md | 45 +++++ .../references/agents/security-sentinel.md | 141 +++++++++++++++ skills/ce-test-browser/SKILL.md | 4 + .../references/element-ui-selectors.md | 161 ++++++++++++++++++ .../references/single-spa-guide.md | 122 +++++++++++++ skills/ce-work/SKILL.md | 2 + .../agents/code-quality-per-task-reviewer.md | 58 +++++++ .../agents/spec-compliance-reviewer.md | 66 +++++++ .../ce-work/references/execution-strategy.md | 6 +- .../ce-work/references/implementation-loop.md | 3 +- skills/ce-work/references/input-triage.md | 2 + skills/ce-work/references/session-state.md | 68 ++++++++ .../ce-work/references/shipping-workflow.md | 1 + .../ce-work/references/subagent-templates.md | 137 +++++++++++++++ skills/ce-work/references/tdd-guardrails.md | 151 ++++++++++++++++ .../references/testing-anti-patterns.md | 119 +++++++++++++ .../references/verification-discipline.md | 96 +++++++++++ tests/release-metadata.test.ts | 2 +- 21 files changed, 1274 insertions(+), 8 deletions(-) create mode 100644 skills/ce-security-audit/SKILL.md create mode 100644 skills/ce-security-audit/references/agents/security-reviewer.md create mode 100644 skills/ce-security-audit/references/agents/security-sentinel.md create mode 100644 skills/ce-test-browser/references/element-ui-selectors.md create mode 100644 skills/ce-test-browser/references/single-spa-guide.md create mode 100644 skills/ce-work/references/agents/code-quality-per-task-reviewer.md create mode 100644 skills/ce-work/references/agents/spec-compliance-reviewer.md create mode 100644 skills/ce-work/references/session-state.md create mode 100644 skills/ce-work/references/subagent-templates.md create mode 100644 skills/ce-work/references/tdd-guardrails.md create mode 100644 skills/ce-work/references/testing-anti-patterns.md create mode 100644 skills/ce-work/references/verification-discipline.md diff --git a/README.md b/README.md index c4175f804..df9ae4550 100644 --- a/README.md +++ b/README.md @@ -8,11 +8,11 @@ [![Build Status](https://github.com/EveryInc/compound-engineering-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/EveryInc/compound-engineering-plugin/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](LICENSE) -[![Skills](https://img.shields.io/badge/skills-33-black.svg)](skills/guides/README.md) +[![Skills](https://img.shields.io/badge/skills-34-black.svg)](skills/guides/README.md) -Compound Engineering is a plugin of 33 skills for AI coding agents. It structures the work around a loop — brainstorm, plan, build, review, then **capture what you learned** — so the knowledge from each change is written down where the next change can read it. +Compound Engineering is a plugin of 34 skills for AI coding agents. It structures the work around a loop — brainstorm, plan, build, review, then **capture what you learned** — so the knowledge from each change is written down where the next change can read it. It runs on 14 agent hosts, including Claude Code, Cursor, and Codex. @@ -170,13 +170,13 @@ Starting from a bug instead of a feature? Use [`/ce-debug`](skills/guides/ce-deb ## Skills at a glance -33 skills, grouped by what they are for. The full catalog, with a page per skill and how each one chains into the others, is in **[skills/guides](skills/guides/README.md)**. +34 skills, grouped by what they are for. The full catalog, with a page per skill and how each one chains into the others, is in **[skills/guides](skills/guides/README.md)**. | Group | Skills | What it covers | |-------|--------|----------------| | [Core loop](skills/guides/README.md#the-core-loop) | `ce-brainstorm` `ce-plan` `ce-work` `ce-simplify-code` `ce-code-review` `ce-compound` | The six steps of every iteration | | [Around the loop](skills/guides/README.md#around-the-loop) | `ce-strategy` `ce-product-pulse` `ce-sweep` `ce-compound-refresh` | Anchors and feeds that keep the loop grounded | -| [On demand](skills/guides/README.md#on-demand) | `ce-ideate` `ce-pov` `ce-debug` `ce-explain` `ce-doc-review` `ce-optimize` `ce-prototype` | Reached for when a specific need arises | +| [On demand](skills/guides/README.md#on-demand) | `ce-ideate` `ce-pov` `ce-debug` `ce-explain` `ce-doc-review` `ce-optimize` `ce-prototype` `ce-security-audit` | Reached for when a specific need arises | | [Git workflow](skills/guides/README.md#git-workflow) | `ce-commit` `ce-commit-push-pr` `ce-babysit-pr` `ce-resolve-pr-feedback` `ce-worktree` | Committing, shipping, and shepherding PRs | | [Autonomous](skills/guides/README.md#autonomous-pipeline) | `lfg` | The whole pipeline, hands-off | | [Testing & design](skills/guides/README.md#frontend-design) | `ce-test-browser` `ce-test-xcode` `ce-polish` `ce-dogfood` | Verifying and polishing what you built | diff --git a/skills/ce-debug/references/fix.md b/skills/ce-debug/references/fix.md index 4a41c80d8..bf5d176ff 100644 --- a/skills/ce-debug/references/fix.md +++ b/skills/ce-debug/references/fix.md @@ -9,7 +9,7 @@ Read this before editing any file in Phase 3. The branch check and the pre-fix s 1. Choose the regression test's home. Follow the active project instructions and any applicable subdirectory-scoped instructions, and always inspect existing tests before adding coverage. Use an existing failing test when it already captures the bug, update an existing test when it owns the contract but has the wrong expectation, strengthen an over-mocked test that should have caught the bug, or add a new minimal isolated test only when no existing test is the right home. It must fail on the current bug and pass once the corrected behavior lands; name it so the failure message explains the bug. The body's precondition decides whether an existing test may be updated at all: a confirmed defect, never a test whose expectation the change deliberately reverses. 2. Verify that test fails for the right reason — the root cause, not unrelated setup. 3. Implement the **minimal** fix: the root cause and nothing else. No drive-by refactors, formatting, or unrelated cleanup — those are separate commits. -4. Verify the test passes, then run the broader suite for regressions. +4. Verify the test passes. Then **revert-and-verify-failure:** revert the fix and run the test — it MUST fail (this proves the test actually catches the bug, not a false positive); restore the fix and confirm the test passes again. If the test still passes with the fix reverted, the test is a false positive — rewrite it. Then run the broader suite for regressions. 5. Self-review the diff — read every changed line for style violations, missed edge cases, regressions in adjacent behavior, and missing coverage. The broader polish/review/PR tail belongs to Phase 4, after the debug summary. **On a failed fix:** return to Phase 2 and *explicitly invalidate the current hypothesis* before forming a new one — state what evidence ruled it out, then form a new hypothesis with its own grounding observation and prediction. Do not retry variants of the same theory ("maybe it was the other branch", "let me also catch this case"); that is the rationalization spiral, not iteration. **3 failed attempts = smart escalation** (same table as Phase 2): if fixes keep failing, the root cause identification was likely wrong. diff --git a/skills/ce-security-audit/SKILL.md b/skills/ce-security-audit/SKILL.md new file mode 100644 index 000000000..d5462482d --- /dev/null +++ b/skills/ce-security-audit/SKILL.md @@ -0,0 +1,88 @@ +--- +name: ce-security-audit +description: "Run an on-demand security audit using OWASP Top 10 and STRIDE threat modeling. Use when you want a quick security check without a full /ce-review, before deploying security-sensitive changes, or when touching auth, payments, user data, or API endpoints." +argument-hint: "[directory path, 'pr', 'diff', or 'full' for full codebase scan]" +--- + +# Security Audit + +Run a focused security audit on the specified scope. This skill dispatches two security review personas — a **security reviewer** and a **security sentinel** — as generic subagents in parallel and combines their findings into a single report. Each persona is a local prompt asset in this skill's own `references/agents/` directory; seed a generic subagent with the prompt file (do not use a typed `Agent`/`subagent_type` name or platform-level agent registration). + +Unlike `/ce-review` (which runs many reviewers across all concerns), this skill runs **only** the security personas — faster and more focused. + +## Input + + #$ARGUMENTS + +## Determine Scope + +Based on the input: + +| Input | Scope | How to gather files | +|-------|-------|-------------------| +| Directory path (e.g., `src/auth/`) | All files in that directory | `Glob` for source files in the path | +| `pr` or `diff` | Changed files in current branch vs main | `git diff --name-only origin/main...HEAD` | +| `full` | Entire codebase | All source files (exclude node_modules, dist, vendor) | +| Empty/no input | Default to `diff` (current branch changes) | Same as `pr` | + +## Execution + +1. **Gather the file list** based on scope above +2. **Read the changed/target files** to build the review context +3. **Dispatch two agents in parallel:** + + **Agent 1: security reviewer** (seed with `references/agents/security-reviewer.md`) + - Attacker-mindset review + - Focus: injection vectors, auth bypass, secrets in code, SSRF, path traversal + + **Agent 2: security sentinel** (seed with `references/agents/security-sentinel.md`) + - Checklist-driven audit + - Focus: OWASP Top 10 compliance + STRIDE threat modeling (Spoofing, Tampering, Repudiation, Information Disclosure, DoS, Elevation of Privilege) + + Provide each agent with: + - The file contents or diff + - The scope description (what area of the codebase this covers) + - Any relevant context from CLAUDE.md about the project's auth, payment, or data handling patterns + +4. **Wait for both agents to complete** +5. **Combine findings** into a single report + +## Output Format + +Present a combined security report: + +### Summary +- Total findings by severity (Critical / High / Medium / Low) +- Overall risk assessment (one sentence) + +### Findings +For each finding (sorted by severity, then by category): + +| # | Severity | Category | File:Line | Description | Remediation | +|---|----------|----------|-----------|-------------|-------------| +| 1 | Critical | OWASP A01 | `src/auth/login.js:45` | Missing authorization check on admin endpoint | Add role verification middleware | +| 2 | High | STRIDE: Spoofing | `src/webhooks/handler.js:12` | Webhook signature not verified | Validate HMAC signature before processing | + +### Clean Areas +Note areas that were reviewed and found clean — this provides confidence, not just a list of problems. + +## Error Handling + +- If one agent fails to dispatch, report findings from the other and note the failure +- If no files match the scope, report "No files found for the specified scope" and suggest alternatives +- If the scope is very large (>100 files), warn about token cost and ask whether to proceed or narrow the scope + +## When to Use This Skill + +- Before deploying changes that touch auth, payments, user data, or API endpoints +- When adding new endpoints or modifying access control +- After a security incident to audit related code +- As a quick check during development — faster than a full `/ce-review` +- When onboarding to unfamiliar code that handles sensitive operations + +## What This Skill Does NOT Do + +- Does not replace static analysis tools (Snyk, SonarQube, npm audit) +- Does not run penetration tests or active exploitation +- Does not scan dependencies for known CVEs +- Does not modify code — report only diff --git a/skills/ce-security-audit/references/agents/security-reviewer.md b/skills/ce-security-audit/references/agents/security-reviewer.md new file mode 100644 index 000000000..7a20b2ae0 --- /dev/null +++ b/skills/ce-security-audit/references/agents/security-reviewer.md @@ -0,0 +1,45 @@ +# Security Reviewer + +You are an application security expert who thinks like an attacker looking for the one exploitable path through the code. You don't audit against a compliance checklist -- you read the diff and ask "how would I break this?" then trace whether the code stops you. + +## What you're hunting for + +- **Injection vectors** -- user-controlled input reaching SQL queries without parameterization, HTML output without escaping (XSS), shell commands without argument sanitization, or template engines with raw evaluation. Trace the data from its entry point to the dangerous sink. +- **Auth and authz bypasses** -- missing authentication on new endpoints, broken ownership checks where user A can access user B's resources, privilege escalation from regular user to admin, CSRF on state-changing operations. +- **Secrets in code or logs** -- hardcoded API keys, tokens, or passwords in source files; sensitive data (credentials, PII, session tokens) written to logs or error messages; secrets passed in URL parameters. +- **Insecure deserialization** -- untrusted input passed to deserialization functions (pickle, Marshal, unserialize, JSON.parse of executable content) that can lead to remote code execution or object injection. +- **SSRF and path traversal** -- user-controlled URLs passed to server-side HTTP clients without allowlist validation; user-controlled file paths reaching filesystem operations without canonicalization and boundary checks. + +## Confidence calibration + +Security findings have a **lower effective threshold** than other personas because the cost of missing a real vulnerability is high. Security findings at anchor 50 should typically be filed at P0 severity so they survive the gate via the P0 exception (P0 + anchor 50 always reports). + +Use the anchored confidence rubric in the subagent template. Persona-specific guidance: + +**Anchor 100** — the vulnerability is verifiable from the code: a literal SQL injection (`f"SELECT ... {user_input}"`), a missing CSRF token where the framework convention requires one, an unauthenticated endpoint with `current_user` referenced in the body. No interpretation needed. + +**Anchor 75** — you can trace the full attack path: untrusted input enters here, passes through these functions without sanitization, and reaches this dangerous sink. The exploit is constructible from the code alone. + +**Anchor 50** — the dangerous pattern is present but you can't fully confirm exploitability — e.g., the input *looks* user-controlled but might be validated in middleware you can't see, or the ORM *might* parameterize automatically. File at P0 if the potential impact is critical so the P0 exception keeps it visible. + +**Anchor 25 or below — suppress** — the attack requires conditions you have no evidence for. + +## What you don't flag + +- **Defense-in-depth suggestions on already-protected code** -- if input is already parameterized, don't suggest adding a second layer of escaping "just in case." Flag real gaps, not missing belt-and-suspenders. +- **Theoretical attacks requiring physical access** -- side-channel timing attacks, hardware-level exploits, attacks requiring local filesystem access on the server. +- **HTTP vs HTTPS in dev/test configs** -- insecure transport in development or test configuration files is not a production vulnerability. +- **Generic hardening advice** -- "consider adding rate limiting," "consider adding CSP headers" without a specific exploitable finding in the diff. These are architecture recommendations, not code review findings. + +## Output format + +Return your findings as JSON matching the findings schema. No prose outside the JSON. + +```json +{ + "reviewer": "security", + "findings": [], + "residual_risks": [], + "testing_gaps": [] +} +``` diff --git a/skills/ce-security-audit/references/agents/security-sentinel.md b/skills/ce-security-audit/references/agents/security-sentinel.md new file mode 100644 index 000000000..c81495d1a --- /dev/null +++ b/skills/ce-security-audit/references/agents/security-sentinel.md @@ -0,0 +1,141 @@ +You are an elite Application Security Specialist with deep expertise in identifying and mitigating security vulnerabilities. You think like an attacker, constantly asking: Where are the vulnerabilities? What could go wrong? How could this be exploited? + +Your mission is to perform comprehensive security audits with laser focus on finding and reporting vulnerabilities before they can be exploited. + +## Core Security Scanning Protocol + +You will systematically execute these security scans: + +1. **Input Validation Analysis** + - Search for all input points: `grep -r "req\.\(body\|params\|query\)" --include="*.js"` + - For Rails projects: `grep -r "params\[" --include="*.rb"` + - Verify each input is properly validated and sanitized + - Check for type validation, length limits, and format constraints + +2. **SQL Injection Risk Assessment** + - Scan for raw queries: `grep -r "query\|execute" --include="*.js" | grep -v "?"` + - For Rails: Check for raw SQL in models and controllers + - Ensure all queries use parameterization or prepared statements + - Flag any string concatenation in SQL contexts + +3. **XSS Vulnerability Detection** + - Identify all output points in views and templates + - Check for proper escaping of user-generated content + - Verify Content Security Policy headers + - Look for dangerous innerHTML or dangerouslySetInnerHTML usage + +4. **Authentication & Authorization Audit** + - Map all endpoints and verify authentication requirements + - Check for proper session management + - Verify authorization checks at both route and resource levels + - Look for privilege escalation possibilities + +5. **Sensitive Data Exposure** + - Execute: `grep -r "password\|secret\|key\|token" --include="*.js"` + - Scan for hardcoded credentials, API keys, or secrets + - Check for sensitive data in logs or error messages + - Verify proper encryption for sensitive data at rest and in transit + +6. **OWASP Top 10 Compliance** + - Systematically check against each OWASP Top 10 vulnerability + - Document compliance status for each category + - Provide specific remediation steps for any gaps + +## Security Requirements Checklist + +For every review, you will verify: + +- [ ] All inputs validated and sanitized +- [ ] No hardcoded secrets or credentials +- [ ] Proper authentication on all endpoints +- [ ] SQL queries use parameterization +- [ ] XSS protection implemented +- [ ] HTTPS enforced where needed +- [ ] CSRF protection enabled +- [ ] Security headers properly configured +- [ ] Error messages don't leak sensitive information +- [ ] Dependencies are up-to-date and vulnerability-free + +## Reporting Protocol + +Your security reports will include: + +1. **Executive Summary**: High-level risk assessment with severity ratings +2. **Detailed Findings**: For each vulnerability: + - Description of the issue + - Potential impact and exploitability + - Specific code location + - Proof of concept (if applicable) + - Remediation recommendations +3. **Risk Matrix**: Categorize findings by severity (Critical, High, Medium, Low) +4. **Remediation Roadmap**: Prioritized action items with implementation guidance + +## Operational Guidelines + +- Always assume the worst-case scenario +- Test edge cases and unexpected inputs +- Consider both external and internal threat actors +- Don't just find problems—provide actionable solutions +- Use automated tools but verify findings manually +- Stay current with latest attack vectors and security best practices +- When reviewing Rails applications, pay special attention to: + - Strong parameters usage + - CSRF token implementation + - Mass assignment vulnerabilities + - Unsafe redirects + +## STRIDE Threat Modeling + +In addition to the OWASP checks above, analyze the code through the STRIDE threat model. For each category, identify concrete threats specific to the code being reviewed. + +### Spoofing (Identity) +- Can an attacker impersonate a legitimate user or service? +- Are authentication tokens properly validated (signature, expiry, issuer)? +- Are webhook signatures verified before processing payloads? +- Can API keys be reused across environments or services? +- Are there endpoints that trust caller identity without verification? + +### Tampering (Data Integrity) +- Can request data be modified in transit or at rest? +- Are critical fields (prices, quantities, permissions) validated server-side, not just client-side? +- Are database writes protected by transactions where atomicity matters? +- Can an attacker modify configuration or environment variables at runtime? +- Are file uploads validated for type, size, and content (not just extension)? + +### Repudiation (Audit Trail) +- Are security-relevant actions logged (login, permission changes, data access, admin operations)? +- Do logs include enough context to reconstruct what happened (who, what, when, from where)? +- Are logs tamper-resistant (not writable by the application user)? +- Can a user deny performing an action because it was not recorded? + +### Information Disclosure +- Do error responses leak internal details (stack traces, SQL errors, file paths, server versions)? +- Are API responses filtered to return only the fields the requester is authorized to see? +- Are secrets, tokens, or PII visible in logs, URLs, or client-side code? +- Are debug endpoints or admin panels accessible in production? +- Does the application expose internal service topology through headers or error messages? + +### Denial of Service +- Are there rate limits on authentication endpoints, API calls, and resource-intensive operations? +- Can a single request trigger unbounded computation (regex, recursion, large file processing)? +- Are database queries bounded (pagination, LIMIT clauses, timeout)? +- Can an attacker exhaust connection pools, file descriptors, or memory? +- Are WebSocket connections limited per client? + +### Elevation of Privilege +- Can a regular user access admin-only endpoints or operations? +- Are role checks enforced at the data layer, not just the UI or routing layer? +- Can a user modify their own role or permissions through API manipulation? +- Are there IDOR (Insecure Direct Object Reference) vulnerabilities where changing an ID grants access to another user's data? +- Are default accounts or roles overly permissive? + +## STRIDE Reporting + +When reporting STRIDE findings, include: +- **Threat category** (e.g., "STRIDE: Elevation of Privilege") +- **Severity** (Critical, High, Medium, Low) +- **Specific code location** (file:line) +- **Attack scenario** (how an attacker would exploit this) +- **Remediation** (concrete fix, not generic advice) + +Trace each user-controlled input to the sink it reaches before clearing it, and report every finding with the concrete attack scenario and remediation above rather than a generic caution. diff --git a/skills/ce-test-browser/SKILL.md b/skills/ce-test-browser/SKILL.md index 2155bd1f9..d2b8a15cf 100644 --- a/skills/ce-test-browser/SKILL.md +++ b/skills/ce-test-browser/SKILL.md @@ -48,3 +48,7 @@ Read `references/route-and-report.md` from this skill's directory before step 3 ## Driver Reference When `agent-browser` is selected as the fallback, read `references/agent-browser-driver.md` from this skill's directory before running its commands. Host-native drivers follow their harness-provided instructions instead. + +## Framework-Specific Guides + +When testing single-spa micro frontend applications, read `references/single-spa-guide.md` for mount detection, cross-app navigation, auth flow, and WebSocket update patterns. When interacting with Element UI components, read `references/element-ui-selectors.md` for teleported component selectors and multi-step interaction patterns. diff --git a/skills/ce-test-browser/references/element-ui-selectors.md b/skills/ce-test-browser/references/element-ui-selectors.md new file mode 100644 index 000000000..217752dff --- /dev/null +++ b/skills/ce-test-browser/references/element-ui-selectors.md @@ -0,0 +1,161 @@ +# Element UI Component Selectors & Interaction Patterns + +Load this reference when interacting with Element UI `~2.13.2` components via `agent-browser`. Element UI teleports many component overlays to `document.body`, outside the Vue app's mount container. This guide covers the selectors and multi-step interaction patterns needed. + +**Version:** These patterns are tested against Element UI `~2.13.2`. Other versions may use different class names or DOM structures. + +## Key Concept: Teleported Components + +Element UI renders dropdown menus, dialogs, popovers, and date pickers as children of `document.body`, not inside the component that triggered them. This means: + +- The trigger element (button, input) is inside your app's mount container (`#messaging`, `#multichannel-sender`) +- The overlay content (dropdown options, dialog body, picker panel) is a sibling of ``, outside your app +- `agent-browser snapshot -i` will show both — look for elements near the bottom of the snapshot that aren't inside your app container + +## el-select (Dropdown Select) + +**DOM structure:** +- Trigger: `.el-select` container with `.el-input` inside +- Dropdown: `.el-select-dropdown` teleported to `body`, contains `.el-select-dropdown__item` elements + +**Interaction pattern:** +``` +1. agent-browser click @select-trigger # Click the el-select input to open +2. agent-browser wait .el-select-dropdown # Wait for dropdown to appear in body +3. agent-browser snapshot -i # Find the option refs +4. agent-browser click @target-option # Click the desired option +5. agent-browser wait 500 # Allow selection to register +``` + +**Finding options:** After step 2, use `agent-browser snapshot -i` to see the dropdown items with their `@eN` refs. Options are `.el-select-dropdown__item` elements. The selected option has class `selected`. + +**Multi-select:** For `el-select` with `multiple` attribute, clicking an option toggles it without closing the dropdown. Click outside or press Escape to close. + +## el-dialog (Modal Dialog) + +**DOM structure:** +- Wrapper: `.el-dialog__wrapper` teleported to `body` +- Dialog: `.el-dialog` inside the wrapper +- Header: `.el-dialog__header` with `.el-dialog__title` +- Body: `.el-dialog__body` +- Footer: `.el-dialog__footer` with action buttons +- Overlay: `.v-modal` backdrop + +**Interaction pattern:** +``` +1. agent-browser click @trigger-button # Click whatever opens the dialog +2. agent-browser wait .el-dialog__wrapper # Wait for dialog wrapper +3. agent-browser snapshot -i # Find form fields and buttons +4. # Interact with dialog content (fill forms, click buttons) +5. agent-browser click @confirm-button # Click confirm/submit in footer +6. agent-browser wait 500 # Allow dialog to close +``` + +**Closing:** Click the X button (`.el-dialog__headerbtn`), click a footer button, or click the overlay (if `close-on-click-modal` is true, which is the default). + +**Nested dialogs:** Element UI supports nested dialogs. Each gets its own `.el-dialog__wrapper` in body. Use `agent-browser snapshot -i` to distinguish between them. + +## el-date-picker + +**DOM structure:** +- Trigger: `.el-date-editor` input +- Panel: `.el-picker-panel` teleported to `body` +- Navigation: `.el-date-picker__header` with prev/next month buttons +- Date cells: `.el-date-table` with `td.available` cells +- Today: `td.today` +- Selected: `td.current` + +**Interaction pattern (select a specific date):** +``` +1. agent-browser click @date-input # Click to open picker +2. agent-browser wait .el-picker-panel # Wait for panel +3. agent-browser snapshot -i # See the calendar +4. # Navigate months if needed: +5. agent-browser click @next-month-button # .el-icon-arrow-right in header +6. agent-browser wait 300 # Allow month transition +7. agent-browser click @target-date-cell # Click the date cell +8. agent-browser wait 500 # Allow picker to close +``` + +**Date range:** For range pickers, the panel shows two months side by side. Click the start date, then the end date. + +**Quick tip:** Use `agent-browser snapshot -i` after opening the picker to find the exact refs for date cells. Each `td` in the date table is interactive. + +## el-popover + +**DOM structure:** +- Trigger: the element with `v-popover` directive +- Content: `.el-popover` teleported to `body` +- Arrow: `.popper__arrow` + +**Interaction pattern:** +``` +1. agent-browser click @popover-trigger # Click or hover to show +2. agent-browser wait .el-popover # Wait for popover +3. agent-browser snapshot -i # Find content refs +4. # Interact with popover content +``` + +**Trigger mode:** Popovers can be triggered by `click`, `hover`, or `focus`. With `agent-browser`, always use click — hover events are unreliable. + +## el-message-box (Confirm/Alert/Prompt) + +**DOM structure:** +- Wrapper: `.el-message-box__wrapper` teleported to `body` +- Box: `.el-message-box` +- Title: `.el-message-box__title` +- Message: `.el-message-box__message` +- Input: `.el-message-box__input` (for prompt type) +- Buttons: `.el-message-box__btns` with cancel and confirm + +**Interaction pattern:** +``` +1. # Message box appears after an action +2. agent-browser wait .el-message-box__wrapper +3. agent-browser snapshot -i # See title, message, buttons +4. agent-browser click @confirm-button # Or @cancel-button +``` + +## el-table + +**DOM structure:** +- Container: `.el-table` +- Header: `.el-table__header-wrapper` +- Body: `.el-table__body-wrapper` with `tr` rows and `td` cells +- Fixed columns: `.el-table__fixed` (if present) + +**Interaction pattern:** +``` +1. agent-browser wait .el-table__body-wrapper # Wait for table to render +2. agent-browser snapshot -i # Find row/cell refs +3. agent-browser click @target-row # Click a row (if clickable) +``` + +**Pagination:** If the table has pagination (`.el-pagination`), use `agent-browser click` on page numbers or next/prev buttons. + +## General Tips + +### Discovering selectors +When you don't know the exact selector: +``` +agent-browser snapshot -i # Shows all interactive elements with @eN refs +``` + +### Waiting for animations +Element UI components have transition animations (default 300ms). After opening/closing overlays, wait at least 300-500ms before interacting with the next element. + +### Z-index stacking +When multiple overlays are open (dialog + popover, or nested dialogs), the latest one has the highest z-index. `agent-browser snapshot -i` shows elements in DOM order, not z-index order — the last overlay in the list is typically the topmost. + +### Hidden elements +If an element exists in the DOM but isn't visible (display: none, visibility: hidden), `agent-browser click` will fail. Use `agent-browser snapshot -i` to check visibility. + +## Troubleshooting + +| Symptom | Likely Cause | Fix | +|---------|-------------|-----| +| Dropdown doesn't appear after clicking select | Another overlay is blocking it | Close other overlays first | +| Can't find dropdown options | They're teleported to body, not inside the select | Use `snapshot -i` to find them at the bottom of the element list | +| Dialog close button doesn't work | Clicking the overlay instead of the X | Use specific `.el-dialog__headerbtn` selector | +| Date picker shows wrong month | Default is current month | Use nav buttons to reach target month before selecting | +| Table rows not clickable | Table doesn't have row-click handler | Check if the table has `@row-click` or specific cell buttons | diff --git a/skills/ce-test-browser/references/single-spa-guide.md b/skills/ce-test-browser/references/single-spa-guide.md new file mode 100644 index 000000000..c48c3a3f5 --- /dev/null +++ b/skills/ce-test-browser/references/single-spa-guide.md @@ -0,0 +1,122 @@ +# Single-SPA Micro Frontend Testing Guide + +Load this reference when testing single-spa micro frontend applications with `agent-browser`. Covers mount detection, cross-app navigation, auth flows, and WebSocket-driven update patterns. + +## Known Limitations + +`agent-browser` has **no JavaScript evaluation capability**. All "framework awareness" in this guide uses DOM-based workarounds: + +- **Mount detection** = waiting for a known DOM element to appear (not detecting the single-spa mount event) +- **WebSocket awareness** = polling for UI changes (not hooking into socket events) +- **State checking** = reading visible DOM content (not querying Vuex store) + +These workarounds are reliable for testing but cannot detect invisible failures (e.g., socket event received but UI didn't update). + +## App Topology + +| App | Base Path | Port (dev) | Mount Element | AMD Output | +|-----|-----------|-----------|---------------|------------| +| Main Shell | `/` | — | `#app` | orchestrator | +| Messaging | `/messaging-portal` | 8240 | `#messaging` | `messaging.js` | +| MCS | `/multichannel-portal` | 8243 | `#multichannel-sender` | `sender.js` | +| Automation | `/automation` | — | TBD | React + Bun | + +## Mount Detection + +Single-spa apps mount/unmount based on route. After navigating to an app's route, wait for its mount element to have child content before interacting. + +**Pattern:** +``` +1. agent-browser navigate /messaging-portal +2. agent-browser wait #messaging # Wait for mount element +3. agent-browser snapshot -i # Verify app content is loaded +4. # Now safe to interact with the app +``` + +**Why not just `wait` for the mount element?** The `#messaging` div may exist in the HTML before the app mounts (it's a static container). Wait for a child element that only appears after the Vue app renders — e.g., a navigation bar, a specific component, or any content inside the container. + +**Better pattern:** +``` +1. agent-browser navigate /messaging-portal +2. agent-browser wait .messaging-sidebar # Wait for a child that proves the app mounted +3. agent-browser snapshot -i +``` + +## Cross-App Navigation + +When navigating between micro frontends, the current app unmounts and the new app mounts. This takes time. + +**Pattern:** +``` +1. # Currently in Messaging at /messaging-portal +2. agent-browser navigate /multichannel-portal +3. agent-browser wait 2000 # Allow unmount/mount cycle +4. agent-browser wait #multichannel-sender # Wait for MCS mount +5. agent-browser snapshot -i # Verify MCS is loaded +``` + +**Common mistake:** Interacting with elements immediately after navigation. The old app's DOM may still be present during the unmount/mount transition. + +## Auth Flow + +### Prerequisites +- Shell app running (serves the login page at `/`) +- Test credentials in environment variables: + - `TEST_USER_EMAIL` — test account email + - `TEST_USER_PASSWORD` — test account password +- Descope auth service reachable + +### Login Pattern +``` +1. agent-browser navigate / +2. agent-browser wait [data-testid="login-form"] # Or the actual login form selector +3. agent-browser fill @email-input $TEST_USER_EMAIL +4. agent-browser fill @password-input $TEST_USER_PASSWORD +5. agent-browser click @login-button +6. agent-browser wait 3000 # Allow auth redirect +7. agent-browser wait .main-shell-content # Verify logged-in state +``` + +### Session Persistence +After login through the shell app, session cookies are set in the browser. Navigating to micro frontend routes (`/messaging-portal`, `/multichannel-portal`) carries the auth state automatically — no need to re-login. + +### Error Handling +If login fails: +1. **Check env vars:** Are `TEST_USER_EMAIL` and `TEST_USER_PASSWORD` set? +2. **Check Descope:** Is the auth service reachable? (may not be available in local dev) +3. **Check 2FA:** Does the test account require two-factor authentication? If so, it cannot be automated with `agent-browser`. +4. **Check rate limiting:** Descope may rate-limit login attempts. Wait and retry. +5. **Take a screenshot:** `agent-browser screenshot --full` to see what the login page shows. + +## WebSocket-Driven Updates + +Our apps use a Vuex socket module for real-time updates (new messages, status changes). Since `agent-browser` cannot hook into WebSocket events, use poll-and-wait patterns. + +**Pattern: Wait for a message to appear** +``` +1. # Trigger the action that should produce a WebSocket event +2. # (e.g., send a message via API, or click send in the UI) +3. agent-browser wait .message-list-item:last-child # Wait for new DOM element +4. agent-browser snapshot -i # Verify content +``` + +**Pattern: Wait for a status change** +``` +1. # Trigger status change +2. agent-browser wait [data-status="active"] # Wait for attribute change +3. agent-browser snapshot -i +``` + +**Timeout guidance:** If the expected UI change doesn't appear within 10 seconds, the event likely didn't arrive or the UI didn't update. Take a screenshot and report the failure rather than waiting indefinitely. + +**What you can't detect:** If a WebSocket event arrives but the UI handler has a bug and doesn't update the DOM, the wait will time out. This is a real limitation — report it as "expected UI change did not appear within timeout" and let the developer investigate. + +## Troubleshooting + +| Symptom | Likely Cause | Fix | +|---------|-------------|-----| +| Mount element exists but app content doesn't load | App hasn't finished mounting | Wait for a child element, not just the container | +| Login succeeds but micro frontend shows "unauthorized" | Session cookie not set correctly | Check if the shell app and micro frontend are on the same domain | +| Elements not found after navigation | Old app's DOM is still present during transition | Add a delay before waiting for the new app's elements | +| WebSocket updates don't appear | Socket not connected, or event handler bug | Check if the dev server's WebSocket endpoint is running | +| `agent-browser wait` times out | Element selector is wrong, or the element is inside a shadow DOM | Use `agent-browser snapshot -i` to inspect available elements | diff --git a/skills/ce-work/SKILL.md b/skills/ce-work/SKILL.md index 09174613e..2f7c4b066 100644 --- a/skills/ce-work/SKILL.md +++ b/skills/ce-work/SKILL.md @@ -19,6 +19,8 @@ argument-hint: "[Plan path, work description, or recovery request with run id; b ### Phase 0: Input Triage +**Session-state check comes first (standalone).** Before input classification, if `SESSION_STATE.md` exists in the project root, read it and `references/session-state.md`, then ask the user whether to resume or start fresh before proceeding. + **Recovery activation comes first.** Before normal plan, path, blank-input, or bare-prompt classification, recognize semantic requests to resume, inspect, reap, or clean up an existing run. Recovery never dispatches a new worker, selects a new route, discovers another plan, reruns completed verification, or enters either shipping tail; a missing run id is requested, never guessed. Before any other input decision, read `references/input-triage.md`. A bare prompt that is Trivial — one or two files, no behavioral change — skips the task list and still passes the engine-before-write gate; a purely mechanical diff also ships without a post-PR watch. When that is uncertain, take the fuller route. A bare prompt this session's `ce-plan` already sized is executed, not re-planned; a decision the user would weigh surfaces as a question, never as a route back to `ce-plan` or `ce-brainstorm`. It owns source resolution, control grammar, recovery, read-only discovery, plan readiness, non-code routing, blank discovery, and bare-prompt intake. An unreadable owner stops triage rather than letting control data or a non-executable artifact fall through as code work. diff --git a/skills/ce-work/references/agents/code-quality-per-task-reviewer.md b/skills/ce-work/references/agents/code-quality-per-task-reviewer.md new file mode 100644 index 000000000..ad966d42a --- /dev/null +++ b/skills/ce-work/references/agents/code-quality-per-task-reviewer.md @@ -0,0 +1,58 @@ +# Code Quality Per-Task Reviewer + +You are a code quality expert who reviews individual subagent task output for cleanliness, test quality, and maintainability. You are dispatched after each subagent task passes spec-compliance review. + +**Core principle:** Per-task quality catches drift early. Issues fixed per-task are cheaper than issues found at PR time. + +**Scope:** You review only the changes from this specific task — not the entire codebase or full PR diff. Stay focused and fast. + +## What You're Hunting For + +1. **Code cleanliness** — Are names clear and accurate? Is the code readable? Any unnecessary complexity, dead code, or debug artifacts (console.log, TODO comments, commented-out code)? + +2. **Test quality** — Do tests verify real behavior, not mock behavior? Is each test minimal and focused on one thing? Are test names descriptive of the behavior being tested? Are mocks used appropriately (see testing anti-patterns)? + +3. **Maintainability** — Does each file have one clear responsibility? Is the implementation following existing codebase patterns? Would a new team member understand this code? + +4. **YAGNI violations** — Did the implementer build beyond what the task specified? Unnecessary abstractions, premature generalization, unused parameters or options? + +5. **File organization** — Is the implementation following the file structure from the plan? Did the change create files that are already large, or significantly grow existing files? + +## Confidence Calibration + +- **Report with HIGH confidence** when you can point to specific code that is clearly wrong, confusing, or violates an established pattern +- **Report with MODERATE confidence** for improvements that would meaningfully reduce future maintenance burden +- **Do not report** subjective style preferences, alternative approaches that are equally valid, or pre-existing issues in untouched code + +## What You Don't Flag + +- Spec compliance issues (that was the previous reviewer's job) +- Pre-existing code quality issues in files the implementer didn't meaningfully change +- Style preferences not grounded in readability or maintainability concerns +- Performance optimizations unless the code has an obvious algorithmic issue (O(n^2) where O(n) is trivial) + +## Severity Levels + +- **Critical** — Will cause bugs, data loss, or security issues. Blocks task completion. +- **Important** — Meaningfully hurts maintainability or violates established patterns. Should be fixed before proceeding. +- **Minor** — Small improvements. Note for the implementer but don't block. + +## Output Format + +```json +{ + "verdict": "APPROVED" | "CHANGES_REQUESTED", + "strengths": ["What the implementer did well"], + "findings": [ + { + "severity": "critical" | "important" | "minor", + "description": "What's wrong", + "evidence": "file:line reference", + "suggestion": "How to fix" + } + ], + "summary": "One-line assessment" +} +``` + +Only critical and important findings block task completion. If the verdict is CHANGES_REQUESTED, the implementer must fix the issues and you must re-review. diff --git a/skills/ce-work/references/agents/spec-compliance-reviewer.md b/skills/ce-work/references/agents/spec-compliance-reviewer.md new file mode 100644 index 000000000..4a9efd817 --- /dev/null +++ b/skills/ce-work/references/agents/spec-compliance-reviewer.md @@ -0,0 +1,66 @@ +# Spec Compliance Reviewer + +You are a spec compliance expert who verifies that an implementer's output matches the plan specification. You are dispatched after each subagent task completes, before the code-quality review. + +**Core principle:** The implementer's self-report is not evidence. Read the actual code. + +## Your Posture + +The implementer finished suspiciously quickly. Their report may be incomplete, inaccurate, or optimistic. You MUST verify everything independently. + +**DO NOT:** +- Take their word for what they implemented +- Trust their claims about completeness +- Accept their interpretation of requirements +- Assume passing tests mean the spec is met + +**DO:** +- Read the actual code they wrote +- Compare actual implementation to the plan unit's requirements line by line +- Check for missing pieces they claimed to implement +- Look for extra features they didn't mention or the spec didn't request + +## What You're Hunting For + +1. **Missing requirements** — Did they implement everything the plan unit specified? Are there requirements they skipped, missed, or claimed to implement but didn't? + +2. **Extra/unneeded work** — Did they build things not requested? Over-engineer? Add "nice to haves" that weren't in the spec? Added features increase maintenance burden. + +3. **Misunderstandings** — Did they interpret requirements differently than intended? Solve the wrong problem? Implement the right feature but the wrong way? + +4. **Test coverage gaps** — Do the test scenarios from the plan unit have corresponding tests? Are there plan-specified edge cases without test coverage? + +5. **File list mismatch** — Were all files listed in the plan unit's `Files:` section actually touched? Were unexpected files modified? + +## Confidence Calibration + +- **Report with HIGH confidence** when you can point to a specific plan requirement and show it's missing from the code, or vice versa +- **Report with MODERATE confidence** when the implementation seems to satisfy the requirement but through an unexpected approach that may not cover all cases +- **Do not report** stylistic preferences, alternative approaches that would also satisfy the spec, or issues that belong in the code-quality review + +## What You Don't Flag + +- Code style or formatting (that's the code-quality reviewer's job) +- Performance concerns (unless the plan explicitly specifies performance requirements) +- Suggestions for improvement beyond the spec +- Pre-existing code issues in files the implementer didn't change + +## Output Format + +```json +{ + "verdict": "PASS" | "FAIL", + "findings": [ + { + "type": "missing_requirement" | "extra_work" | "misunderstanding" | "test_gap" | "file_mismatch", + "severity": "critical" | "important", + "description": "What's wrong", + "evidence": "file:line reference or specific code", + "plan_reference": "Which plan requirement this relates to" + } + ], + "summary": "One-line assessment" +} +``` + +Only critical and important findings block task completion. If the verdict is FAIL, the implementer must fix the issues and you must re-review. diff --git a/skills/ce-work/references/execution-strategy.md b/skills/ce-work/references/execution-strategy.md index b29e8d6fd..0f40d8b2a 100644 --- a/skills/ce-work/references/execution-strategy.md +++ b/skills/ce-work/references/execution-strategy.md @@ -47,7 +47,11 @@ Give each native worker: **Permission mode:** Omit the `mode` parameter when dispatching subagents so the user's configured permission settings apply. Do not pass `mode: "auto"` — it overrides user-level settings like `bypassPermissions`. -**After each serial inline/subagent unit:** review the diff against the unit's scope and `Files:`, run the relevant tests, fix before starting the next (never on a broken tree), record the unit's verification evidence (from the worker's return when a worker ran), update the task list (never edit the plan body — progress lives in commits), and commit. If the unit used a native subagent worker, retire its handle (closing/releasing it only when the harness exposes that operation and assigns that lifecycle action to the caller), then dispatch the next subagent unit in a new worker context. An inline unit has no worker handle to retire; start the next unit directly. +**Subagent prompt and status handling:** Read `references/subagent-templates.md` for the implementer prompt template, the status vocabulary (DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED), the escalation decision trees, and model-tier routing. When a worker returns NEEDS_CONTEXT, supply the missing context and re-dispatch; when BLOCKED, follow the escalation tree (context problem -> re-dispatch, reasoning limit -> upgrade model, task too large -> split, plan wrong -> escalate to the user). + +**Per-task review (after a serial unit reports DONE, before the next unit):** run the two-stage review from `references/subagent-templates.md`. First dispatch a generic subagent seeded with `references/agents/spec-compliance-reviewer.md`; only after spec-compliance passes, dispatch a generic subagent seeded with `references/agents/code-quality-per-task-reviewer.md`. If either raises critical or important findings, the implementer fixes them and the reviewer re-reviews until both approve. Do not start the code-quality review before spec-compliance passes, and do not advance to the next unit while either review has open issues. + +**After each serial inline/subagent unit:** review the diff against the unit's scope and `Files:`, run the per-task review above, run the relevant tests, fix before starting the next (never on a broken tree), record the unit's verification evidence (from the worker's return when a worker ran), update the task list (never edit the plan body — progress lives in commits), and commit. If the unit used a native subagent worker, retire its handle (closing/releasing it only when the harness exposes that operation and assigns that lifecycle action to the caller), then dispatch the next subagent unit in a new worker context. An inline unit has no worker handle to retire; start the next unit directly. **After a parallel inline/subagent batch — the orchestrator integrates; never trust the handoff summary alone:** 1. Wait for every worker in the batch to finish. diff --git a/skills/ce-work/references/implementation-loop.md b/skills/ce-work/references/implementation-loop.md index fa4fd5a3b..f625fb01d 100644 --- a/skills/ce-work/references/implementation-loop.md +++ b/skills/ce-work/references/implementation-loop.md @@ -15,7 +15,7 @@ while (tasks remain): - Find existing test files for implementation files being changed (Test Discovery — see below) - Choose the evidence strategy for this task before changing behavior: use an existing failing test, update or strengthen an existing test, add a new failing test, add characterization coverage, or record a deliberate no-test exception with replacement verification - For behavior-bearing changes, default to test-first or characterization-first when the current code and test surface make that practical, even if the plan has no `Execution note` - - When the evidence strategy calls for pre-implementation proof, create/update/strengthen the test or characterization coverage now and verify the expected failure or baseline capture before changing production code + - When the evidence strategy calls for pre-implementation proof, create/update/strengthen the test or characterization coverage now and verify the expected failure or baseline capture before changing production code. When working test-first, read `references/tdd-guardrails.md` for rationalization defenses, red-flag detection, and the delete-and-restart rule, and `references/testing-anti-patterns.md` for common testing pitfalls to avoid. - Implement following existing conventions - Add, update, or remove any remaining tests needed to match implementation changes (see Test Discovery below) - Run System-Wide Test Check (see below) @@ -23,6 +23,7 @@ while (tasks remain): - Assess testing coverage: did this task change behavior? If yes, were existing tests inspected and were tests written, updated, strengthened, or deliberately left unchanged with a reason? If no tests were added or changed, is the justification deliberate (e.g., pure config, no behavioral change, manual-only surface) and paired with replacement verification? - Record verification evidence for the task: behavior-change signal, existing tests inspected, tests added/changed/used unchanged, red failure or characterization observed when applicable, verification run, and any exception reason - Mark task as completed + - Update `SESSION_STATE.md` with current task progress (see `references/session-state.md` for the format). Orchestrator-level only — never write it from inside a subagent. - Evaluate for incremental commit (see below) ``` diff --git a/skills/ce-work/references/input-triage.md b/skills/ce-work/references/input-triage.md index ec89afd2b..260d22830 100644 --- a/skills/ce-work/references/input-triage.md +++ b/skills/ce-work/references/input-triage.md @@ -22,6 +22,8 @@ This skill discovers plans under `/plans/`. Resolve `` when you firs ## Recovery and Control Grammar +**Session-state check comes first (standalone mode).** Before any input classification — including recovery activation below — check whether `SESSION_STATE.md` exists in the project root (`test -f SESSION_STATE.md`). If it exists, read it and read `references/session-state.md` for resume behavior, present the recorded state to the user, and ask whether to resume from it or start fresh; do not proceed to classification until the user responds. If it does not exist, continue. This local resume mechanism is distinct from the run-id recovery below (which targets external cross-model runs); do not conflate the two. In Return-to-Caller Mode the caller owns continuation state, so skip this check. + **Recovery activation comes first.** Before normal plan, path, blank-input, or bare-prompt classification, interpret whether the user is semantically asking to resume, inspect status, reap, or clean up an existing external implementation run and has supplied its run id. This is intent recognition, not verb-only matching. Validate the id with the controller's safe-id contract: `^[A-Za-z0-9._-]{1,128}$` and at least one non-period character. When this direct recovery intent is present, read `references/cross-model-execution.md`, use that run id as authoritative for the requested controller operation, and return the observed state or blocker. Recovery must not dispatch a new worker, select a new route, fall through to latest-plan discovery, or run either shipping tail. When every unit is already cleaned, **completed recovery is read-only reconciliation**: Do not rerun test, build, format, install, generation, or `verify-run`; report the stored unit and plan-wide verification receipts. If recovery intent is clear but the run id is missing, request the id instead of guessing or classifying the text as new work. **Otherwise, parse a leading mode token.** If `` begins with `mode:return-to-caller` (or the legacy aliases `mode:caller-owned-tail` / `caller:lfg`), strip that token before anything else and enter **Return-to-Caller Mode** — implement and locally verify only, then return the structured envelope instead of running the standalone shipping tail. Before the plan path, accept up to two optional carriers in this fixed order: first one compact JSON object prefixed exactly `implementation_engine:`, then one run id prefixed exactly `implementation_run:`. Fully validate and normalize both before any workspace action. The engine object must contain exactly four fields: `mode` is `prefer` or `require`; `target` is `codex`, `claude`, `grok`, `cursor`, or `composer`; `model` is a string pin or `null`; and `source` is a non-empty caller-visible provenance string. The run carrier is accepted only for return-to-caller recovery and must satisfy the safe-id contract above. Reject malformed JSON, missing/extra fields, invalid field types or values, an unsafe run id, an out-of-order carrier, or a duplicate carrier. The entire remaining string is the plan path. A mode token or carrier with no following path is an error; report it instead of treating control data as a bare prompt. Without either optional carrier, the original `mode:return-to-caller ` form is unchanged and standing configuration remains eligible. diff --git a/skills/ce-work/references/session-state.md b/skills/ce-work/references/session-state.md new file mode 100644 index 000000000..b528eeb6a --- /dev/null +++ b/skills/ce-work/references/session-state.md @@ -0,0 +1,68 @@ +# Session State Persistence + +Load this reference when `/ce-work` detects a `SESSION_STATE.md` file in the project root, or when updating task progress at task boundaries. + +## Purpose + +Persist live work state across Claude Code sessions. When a session ends mid-work and a new session starts, the engineer can resume from where they left off instead of re-explaining context. + +This is NOT a replacement for MEMORY.md (which handles decisions and patterns) or the CE artifact root's `solutions/` tree (which handles post-hoc learnings). SESSION_STATE.md captures **live progress** — what branch you're on, what plan you're executing, which tasks are done, and what's next. + +## SESSION_STATE.md Template + +```markdown +# Session State + +**Updated:** 2026-04-21T14:30:00+08:00 +**Branch:** feat/OMG-1234-user-auth-flow +**Plan:** /plans/2026-04-21-001-feat-user-auth-flow-plan.md + +## Task Progress + +- [x] Unit 1: Create auth service module +- [x] Unit 2: Add login endpoint +- [ ] Unit 3: Add session persistence ← in progress +- [ ] Unit 4: Add logout +- [ ] Unit 5: Add registration + +## Blockers + +- Waiting on Descope API key for staging environment (asked Anton 2026-04-21) + +## Next Steps + +- Complete Unit 3 session persistence +- Then Unit 4 logout (depends on Unit 3) +``` + +## Read Behavior (Phase 0) + +When `/ce-work` starts: + +1. Check for `SESSION_STATE.md` in the project root +2. If it does not exist — proceed normally, no action needed +3. If it exists, read it and check the timestamp +4. **Stale check:** If the `Updated` timestamp is older than 7 days, ask: "Found session state from [date] on branch [branch]. This is [N] days old. Resume from this state, or start fresh?" (Note: 7 days is a starting default — teams with longer branch lifetimes may want to adjust.) +5. **Branch check:** If the state references a different branch than the current one, flag: "Session state is from branch [recorded branch] but you're on [current branch]. This state may be outdated." +6. **Fresh state:** If the state is recent and matches the current branch, offer: "Found session state: [N] of [M] tasks complete on [plan name]. Resume from [next incomplete task]?" +7. If the user chooses to resume, load the plan and skip to the first incomplete task +8. If the user chooses to start fresh, proceed normally (the old state file will be overwritten as new tasks complete) + +## Write Behavior (Phase 2) + +Update `SESSION_STATE.md` at these checkpoints during `/ce-work`: + +1. **Task completion:** After marking a task as completed and before dispatching the next task, update the task checklist in SESSION_STATE.md +2. **Blocker encountered:** When a task is blocked (waiting on external input, dependency not met), update the Blockers section +3. **Plan change:** If scope changes during execution (new tasks added, tasks removed), update the Task Progress section + +**Critical: Orchestrator-level only.** Never update SESSION_STATE.md from inside a subagent. The orchestrating ce-work session handles all writes. This prevents concurrent write conflicts during parallel subagent execution. + +**Token cost:** Each update is one `Write` call with ~10-20 lines of markdown. This is lightweight. The agent uses judgment on frequency — don't update after trivial steps (renaming a variable), do update after meaningful task boundaries. + +## File Location and Lifecycle + +- **Location:** Project root (alongside `CLAUDE.md`) +- **Git:** Add `SESSION_STATE.md` to `.gitignore` — each developer's state is personal +- **Cleanup:** When all tasks in a plan are complete, the state file can be deleted or left to be overwritten by the next plan execution +- **Format:** Plain markdown, human-readable and editable. An engineer can manually update it if the agent's version gets out of sync diff --git a/skills/ce-work/references/shipping-workflow.md b/skills/ce-work/references/shipping-workflow.md index 663049019..53aa76a9b 100644 --- a/skills/ce-work/references/shipping-workflow.md +++ b/skills/ce-work/references/shipping-workflow.md @@ -61,6 +61,7 @@ This file contains the shipping workflow (Phase 3-4). It is loaded when all Phas Skip this gate entirely when the review reported `Actionable findings: none.` (and followup applied everything mechanical), or when dedicated review was skipped (mechanical diff or `ce-code-review` unavailable). Do not proceed past this gate on an `Accept and proceed` decision (including the autonomous auto-accept above) until the agent has recorded which durable sink held the residuals — `PR Known Residuals`, a tracker ticket, or an explicit statement in the run report when neither was reachable. 5. **Final Validation** + - Before making any completion claim, read `references/verification-discipline.md` for per-message verification freshness, claim-to-evidence mapping, and linguistic red-flag detection; every "done"/"passing"/"fixed" claim must map to a fresh observed result, not a remembered or inferred one. - All tasks marked completed - Testing addressed -- tests pass and new/changed behavior has corresponding test coverage (or an explicit justification for why tests are not needed) - Linting passes diff --git a/skills/ce-work/references/subagent-templates.md b/skills/ce-work/references/subagent-templates.md new file mode 100644 index 000000000..6c18060e9 --- /dev/null +++ b/skills/ce-work/references/subagent-templates.md @@ -0,0 +1,137 @@ +# Subagent Orchestration Templates + +Load this reference when dispatching subagents for plan execution. It provides the implementer prompt template, status vocabulary with escalation decision trees, and model-tier routing guidance. + +Adapted from [Superpowers](https://github.com/obra/superpowers) `subagent-driven-development` skill. + +## Implementer Prompt Template + +When dispatching a subagent for a plan task, use this template structure: + +``` +You are implementing Task N: [task name] + +## Task Description + +[FULL TEXT of the implementation unit from the plan — paste it here, don't make the subagent read the file] + +## Context + +[Scene-setting: where this fits in the larger plan, what was completed before, architectural context] + +## Before You Begin + +If you have questions about the requirements, approach, dependencies, or anything unclear — ask them now. Raise concerns before starting work. It's always OK to pause and clarify. Don't guess. + +## Your Job + +1. Implement exactly what the task specifies +2. Write tests following TDD (write failing test first, then minimal code to pass) +3. Verify implementation works +4. Commit your work +5. Self-review (see below) +6. Report back with status + +## Self-Review Before Reporting + +Review your work with fresh eyes: + +**Completeness:** Did I implement everything in the spec? Miss any requirements or edge cases? +**Quality:** Is this my best work? Are names clear? Is the code clean and maintainable? +**Discipline:** Did I avoid overbuilding (YAGNI)? Did I follow existing codebase patterns? +**Testing:** Do tests verify behavior (not mock behavior)? Did I follow TDD? Are tests comprehensive? + +If you find issues during self-review, fix them before reporting. + +## When You're In Over Your Head + +It is always OK to stop and escalate. Bad work is worse than no work. + +STOP and escalate when: +- The task requires architectural decisions with multiple valid approaches +- You need to understand code beyond what was provided +- You feel uncertain about whether your approach is correct +- The task involves restructuring code the plan didn't anticipate + +## Report Format + +- **Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT +- What you implemented (or attempted, if blocked) +- What you tested and test results +- Files changed +- Self-review findings (if any) +- Issues or concerns +``` + +## Status Vocabulary + +Subagents report one of four statuses. Handle each with the decision tree below. + +### DONE + +Subagent completed the task successfully. Proceed to per-task review (spec-compliance, then code-quality). + +### DONE_WITH_CONCERNS + +Subagent completed the work but flagged doubts. + +**Decision tree:** +- Read the concerns before proceeding +- If concerns are about **correctness or scope** → address them before review +- If concerns are **observations** (e.g., "this file is getting large") → note them and proceed to review + +### NEEDS_CONTEXT + +Subagent needs information that wasn't provided. + +**Decision tree:** +- Read what context is missing +- Provide the missing context (file contents, architectural decisions, API details) +- Re-dispatch the same subagent with the additional context + +### BLOCKED + +Subagent cannot complete the task. + +**Decision tree:** +1. **Context problem** → Provide more context and re-dispatch with the same model +2. **Reasoning limit** → Re-dispatch with a more capable model +3. **Task too large** → Break into smaller pieces and dispatch separately +4. **Plan is wrong** → Escalate to the user — the plan needs revision + +**Never** ignore an escalation or force the same model to retry without changes. If the subagent said it's stuck, something needs to change. + +## Model-Tier Routing + +Use the least powerful model that can handle each role to conserve cost and increase speed. + +| Task Type | Model Tier | Signals | +|-----------|-----------|---------| +| **Mechanical implementation** | Fast/cheap | Touches 1-2 files, clear spec, isolated function, well-defined inputs/outputs | +| **Integration and judgment** | Standard | Touches multiple files, pattern matching, coordination between components, debugging | +| **Architecture, design, review** | Most capable | Requires design judgment, broad codebase understanding, review quality assessment | + +**Heuristic:** If the plan unit has a complete spec with exact file paths, test scenarios, and patterns to follow — it's mechanical. If it requires the agent to make design decisions — use a more capable model. + +## Per-Task Review Pipeline + +After each subagent completes with DONE status: + +1. **Spec-compliance review** — Dispatch a generic subagent seeded with the local prompt asset `references/agents/spec-compliance-reviewer.md` from this skill's directory (do not use a typed `Agent`/`subagent_type` name or platform-level agent registration). Does the output match the plan unit's Goal, Files, Approach, and Test scenarios? The reviewer explicitly distrusts the implementer's self-report and verifies by reading actual code. + +2. **Code-quality review** — Only after spec-compliance passes. Dispatch a generic subagent seeded with the local prompt asset `references/agents/code-quality-per-task-reviewer.md` from this skill's directory. Is the code clean, tested, and maintainable? + +3. **Fix-and-re-review loop** — If either reviewer raises critical issues, the implementer fixes them and the reviewer re-reviews. Repeat until approved. + +**Important:** Do not start code-quality review before spec-compliance passes. Wrong order wastes review effort on code that doesn't meet the spec. + +## Red Flags + +- Dispatching multiple implementation subagents in parallel on overlapping files (conflicts) +- Making subagent read the plan file (provide full text instead) +- Skipping scene-setting context (subagent needs to know where the task fits) +- Ignoring subagent questions (answer before letting them proceed) +- Accepting "close enough" on spec compliance (issues found = not done) +- Skipping re-review after fixes (reviewer found issues → implementer fixes → review again) +- Letting implementer self-review replace actual review (both are needed) +- Moving to next task while either review has open issues diff --git a/skills/ce-work/references/tdd-guardrails.md b/skills/ce-work/references/tdd-guardrails.md new file mode 100644 index 000000000..f36da1cb8 --- /dev/null +++ b/skills/ce-work/references/tdd-guardrails.md @@ -0,0 +1,151 @@ +# TDD Guardrails + +Load this reference when working test-first. It provides rationalization defenses, red-flag detection, and the delete-and-restart rule to prevent the agent from cutting corners on TDD discipline. + +Adapted from [Superpowers](https://github.com/obra/superpowers) `test-driven-development` skill. + +## The Iron Law + +``` +NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST +``` + +Write code before the test? **Delete it. Start over.** + +- Don't keep it as "reference" +- Don't "adapt" it while writing tests +- Don't look at it +- Delete means delete + +Implement fresh from tests. Period. + +**Exception:** Pure configuration, styling, and documentation work are exempt from test-first (per CE's existing pragmatic rule). This guardrail applies to code that has behavior. + +## Red-Green-Refactor + +### RED — Write Failing Test + +Write one minimal test showing what should happen. + +**Good test:** +```typescript +test('retries failed operations 3 times', async () => { + let attempts = 0; + const operation = () => { + attempts++; + if (attempts < 3) throw new Error('fail'); + return 'success'; + }; + + const result = await retryOperation(operation); + + expect(result).toBe('success'); + expect(attempts).toBe(3); +}); +``` +Clear name, tests real behavior, one thing. + +**Bad test:** +```typescript +test('retry works', async () => { + const mock = jest.fn() + .mockRejectedValueOnce(new Error()) + .mockRejectedValueOnce(new Error()) + .mockResolvedValueOnce('success'); + await retryOperation(mock); + expect(mock).toHaveBeenCalledTimes(3); +}); +``` +Vague name, tests mock not code. + +### Verify RED — Watch It Fail (MANDATORY) + +Run the test. Confirm: +- Test fails (not errors) +- Failure message is expected +- Fails because feature missing (not typos) + +Test passes? You're testing existing behavior. Fix the test. + +### GREEN — Minimal Code + +Write the simplest code to pass the test. Don't add features, refactor other code, or "improve" beyond the test. + +### Verify GREEN — Watch It Pass (MANDATORY) + +Run the test. Confirm all tests pass. Other tests still pass. Output is clean. + +### REFACTOR — Clean Up (After Green Only) + +Remove duplication, improve names, extract helpers. Keep tests green. Don't add behavior. + +## Good Tests + +| Quality | Good | Bad | +|---------|------|-----| +| **Minimal** | One thing. "and" in name? Split it. | `test('validates email and domain and whitespace')` | +| **Clear** | Name describes behavior | `test('test1')` | +| **Shows intent** | Demonstrates desired API | Obscures what code should do | +| **Real code** | Tests actual implementation | Tests mock behavior | + +## Common Rationalizations + +These are the excuses the agent generates to skip TDD. Each one is wrong. + +| Rationalization | Rebuttal | +|----------------|----------| +| "Too simple to test" | Simple code breaks. Test takes 30 seconds. | +| "I'll test after" | Tests passing immediately prove nothing. | +| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" | +| "Already manually tested" | Ad-hoc is not systematic. No record, can't re-run. | +| "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. | +| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. | +| "Need to explore first" | Fine. Throw away exploration, start with TDD. | +| "Test is hard = skip it" | Hard to test = hard to use. Listen to the test. | +| "TDD will slow me down" | TDD is faster than debugging. Pragmatic = test-first. | +| "Manual test is faster" | Manual doesn't prove edge cases. You'll re-test every change. | +| "Existing code has no tests" | You're improving it. Add tests for the code you're changing. | + +## Red Flags — STOP and Start Over + +If you catch yourself thinking any of these, **delete the code and start with a failing test:** + +- Code before test +- Test after implementation +- Test passes immediately (without failing first) +- Can't explain why the test failed +- Tests added "later" +- Rationalizing "just this once" +- "I already manually tested it" +- "Tests after achieve the same purpose" +- "It's about spirit not ritual" +- "Keep as reference" or "adapt existing code" +- "Already spent X hours, deleting is wasteful" +- "TDD is dogmatic, I'm being pragmatic" +- "This is different because..." + +**All of these mean: Delete code. Start over with TDD.** + +## Verification Checklist + +Before marking any unit complete: + +- [ ] Every new function/method has a test +- [ ] Watched each test fail before implementing +- [ ] Each test failed for expected reason (feature missing, not typo) +- [ ] Wrote minimal code to pass each test +- [ ] All tests pass +- [ ] Output is clean (no errors, warnings) +- [ ] Tests use real code (mocks only if unavoidable) +- [ ] Edge cases and error paths covered + +Can't check all boxes? You skipped TDD. Start over. + +## When Stuck + +| Problem | Solution | +|---------|----------| +| Don't know how to test | Write wished-for API. Write assertion first. Ask the user. | +| Test too complicated | Design too complicated. Simplify interface. | +| Must mock everything | Code too coupled. Use dependency injection. | +| Test setup huge | Extract helpers. Still complex? Simplify design. | diff --git a/skills/ce-work/references/testing-anti-patterns.md b/skills/ce-work/references/testing-anti-patterns.md new file mode 100644 index 000000000..b099e141b --- /dev/null +++ b/skills/ce-work/references/testing-anti-patterns.md @@ -0,0 +1,119 @@ +# Testing Anti-Patterns + +Load this reference when writing or changing tests, adding mocks, or tempted to add test-only methods to production code. + +Adapted from [Superpowers](https://github.com/obra/superpowers) `testing-anti-patterns` reference. + +## The Iron Laws + +``` +1. NEVER test mock behavior +2. NEVER add test-only methods to production classes +3. NEVER mock without understanding dependencies +``` + +## Anti-Pattern 1: Testing Mock Behavior + +**The violation:** Asserting that a mock exists rather than testing real component behavior. + +```typescript +// BAD: Testing that the mock exists +test('renders sidebar', () => { + render(); + expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument(); +}); +``` + +**Why it's wrong:** You're verifying the mock works, not that the component works. Test passes when mock is present, tells you nothing about real behavior. + +**The fix:** Test real component behavior, or don't mock it. + +```typescript +// GOOD: Test real component +test('renders sidebar', () => { + render(); + expect(screen.getByRole('navigation')).toBeInTheDocument(); +}); +``` + +**Gate:** Before asserting on any mock element, ask: "Am I testing real behavior or just mock existence?" If mock existence — delete the assertion. + +## Anti-Pattern 2: Test-Only Methods in Production + +**The violation:** Adding methods to production classes that only tests call (e.g., `destroy()`, `reset()`, `_testHelper()`). + +**Why it's wrong:** Pollutes production code with test concerns. Dangerous if accidentally called in production. Confuses object lifecycle. + +**The fix:** Put test cleanup and helpers in test utility files, not production classes. + +**Gate:** Before adding any method to a production class, ask: "Is this only used by tests?" If yes — put it in test utilities instead. + +## Anti-Pattern 3: Mocking Without Understanding + +**The violation:** Over-mocking to "be safe" and accidentally removing behavior the test depends on. + +```typescript +// BAD: Mock prevents config write that test depends on +vi.mock('ToolCatalog', () => ({ + discoverAndCacheTools: vi.fn().mockResolvedValue(undefined) +})); +// Test fails mysteriously because mocked method had a side effect +``` + +**Why it's wrong:** The mocked method had side effects the test depended on. Over-mocking breaks actual behavior. + +**The fix:** Mock at the correct level — mock the slow/external operation, not the high-level method. + +**Gate:** Before mocking any method: +1. What side effects does the real method have? +2. Does this test depend on any of those side effects? +3. If yes — mock at a lower level that preserves necessary behavior + +Red flags: "I'll mock this to be safe", "This might be slow, better mock it", mocking without understanding the dependency chain. + +## Anti-Pattern 4: Incomplete Mocks + +**The violation:** Partial mocks that only include fields you think you need. + +```typescript +// BAD: Missing metadata that downstream code uses +const mockResponse = { + status: 'success', + data: { userId: '123', name: 'Alice' } + // Missing: metadata.requestId consumed downstream +}; +``` + +**Why it's wrong:** Partial mocks hide structural assumptions. Tests pass but integration fails. + +**The fix:** Mirror the complete real data structure. + +**Gate:** Before creating mock responses, check: "What fields does the real API response contain?" Include ALL fields the system might consume downstream. + +## Anti-Pattern 5: Integration Tests as Afterthought + +**The violation:** Claiming implementation is complete without writing tests. + +**Why it's wrong:** Testing is part of implementation, not optional follow-up. TDD prevents this entirely. + +**The fix:** Follow the TDD cycle. Tests come first, not after. + +## Quick Reference + +| Anti-Pattern | Fix | +|--------------|-----| +| Assert on mock elements | Test real component or unmock it | +| Test-only methods in production | Move to test utilities | +| Mock without understanding | Understand dependencies first, mock minimally | +| Incomplete mocks | Mirror real API completely | +| Tests as afterthought | TDD — tests first | +| Over-complex mocks | Consider integration tests | + +## Red Flags + +- Assertion checks for `*-mock` test IDs +- Methods only called in test files +- Mock setup is >50% of test code +- Test fails when you remove mock +- Can't explain why mock is needed +- Mocking "just to be safe" diff --git a/skills/ce-work/references/verification-discipline.md b/skills/ce-work/references/verification-discipline.md new file mode 100644 index 000000000..73df15561 --- /dev/null +++ b/skills/ce-work/references/verification-discipline.md @@ -0,0 +1,96 @@ +# Verification Discipline + +Load this reference during the shipping phase. It enforces evidence-based completion claims, prevents premature success declarations, and provides the revert-verify-failure pattern for regression tests. + +Adapted from [Superpowers](https://github.com/obra/superpowers) `verification-before-completion` skill. + +## The Iron Law + +``` +NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE +``` + +If you haven't run the verification command **in this message**, you cannot claim it passes. + +## The Gate Function + +Before claiming any status or expressing satisfaction: + +1. **IDENTIFY** — What command proves this claim? +2. **RUN** — Execute the full command (fresh, complete) +3. **READ** — Full output, check exit code, count failures +4. **VERIFY** — Does output confirm the claim? + - If NO: State actual status with evidence + - If YES: State claim WITH evidence +5. **ONLY THEN** — Make the claim + +Skip any step = lying, not verifying. + +## Claim-to-Evidence Mapping + +| Claim | Requires | NOT Sufficient | +|-------|----------|----------------| +| "Tests pass" | Test command output: 0 failures | Previous run, "should pass" | +| "Linter clean" | Linter output: 0 errors | Partial check, extrapolation | +| "Build succeeds" | Build command: exit 0 | Linter passing, "logs look good" | +| "Bug fixed" | Test original symptom: passes | "Code changed, assumed fixed" | +| "Regression test works" | Red-green cycle verified | Test passes once | +| "Agent completed" | VCS diff shows changes | Agent reports "success" | +| "Requirements met" | Line-by-line checklist | "Tests passing" | + +## Linguistic Red Flags — STOP + +If you catch yourself using any of these phrases, STOP and run verification: + +- "should work now" +- "probably fine" +- "seems to work" +- "looks correct" +- "I'm confident this..." +- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!") +- About to commit/push/PR without verification +- Trusting agent success reports without independent verification +- **ANY wording implying success without having run verification** + +## Rationalization Prevention + +| Rationalization | Rebuttal | +|----------------|----------| +| "Should work now" | RUN the verification | +| "I'm confident" | Confidence is not evidence | +| "Just this once" | No exceptions | +| "Linter passed" | Linter is not a compiler | +| "Agent said success" | Verify independently | +| "I'm tired" | Exhaustion is not an excuse | +| "Partial check is enough" | Partial proves nothing | +| "Different words so rule doesn't apply" | Spirit over letter | + +## Revert-and-Verify-Failure Pattern + +For regression tests (bug fix TDD), prove the test is not a false positive: + +``` +1. Write regression test +2. Run → MUST PASS (fix is in place) +3. Revert the fix +4. Run → MUST FAIL (proves test catches the bug) +5. Restore the fix +6. Run → MUST PASS again +``` + +If the test passes even with the fix reverted, the test is a false positive — it doesn't actually catch the bug. Rewrite the test. + +## When To Apply + +**ALWAYS before:** +- Any variation of success or completion claims +- Any expression of satisfaction about work state +- Committing, PR creation, task completion +- Moving to next task +- Delegating to agents and trusting their reports + +**The rule applies to:** +- Exact phrases +- Paraphrases and synonyms +- Implications of success +- ANY communication suggesting completion or correctness diff --git a/tests/release-metadata.test.ts b/tests/release-metadata.test.ts index f48b187e1..3ffe0451a 100644 --- a/tests/release-metadata.test.ts +++ b/tests/release-metadata.test.ts @@ -215,7 +215,7 @@ describe("release metadata", () => { expect(counts).toEqual({ agents: 0, - skills: 33, + skills: 34, mcpServers: 0, }) }) From 9f9f2eb24f43f7f366b23e311c1f38fe0e596a45 Mon Sep 17 00:00:00 2001 From: Raymond Torino Date: Thu, 27 Aug 2026 15:29:49 +0800 Subject: [PATCH 2/2] feat(ce-work,ce-security-audit): re-port ruflo integration and trajectory capture Re-applies the fork's ruflo-agentdb integration onto the new agent-native structure, on top of the re-ported base customizations on main. - ce-work: optional ruflo memory enrichment at session start (input-triage) and conditional trajectory capture after shipping (shipping-workflow), both woven into reference files so the kernel SKILL.md stays under the Codex 8000-byte budget; new ruflo-memory-integration.md and trajectory-capture.md references; model-selection scoring table added to subagent-templates. - ce-security-audit: optional ruflo security_scan step for CVE / shell-injection / secrets-at-rest coverage, merged and deduplicated with the CE persona findings. - trajectory-capture writes under the configurable CE artifact root's solutions/ tree (no hardcoded docs/ path) and references the learnings-researcher persona. Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/ce-security-audit/SKILL.md | 11 +++- skills/ce-work/references/input-triage.md | 2 + .../references/ruflo-memory-integration.md | 59 +++++++++++++++++ .../ce-work/references/shipping-workflow.md | 1 + .../ce-work/references/subagent-templates.md | 15 +++++ .../ce-work/references/trajectory-capture.md | 65 +++++++++++++++++++ 6 files changed, 150 insertions(+), 3 deletions(-) create mode 100644 skills/ce-work/references/ruflo-memory-integration.md create mode 100644 skills/ce-work/references/trajectory-capture.md diff --git a/skills/ce-security-audit/SKILL.md b/skills/ce-security-audit/SKILL.md index d5462482d..9abe85687 100644 --- a/skills/ce-security-audit/SKILL.md +++ b/skills/ce-security-audit/SKILL.md @@ -45,7 +45,13 @@ Based on the input: - Any relevant context from CLAUDE.md about the project's auth, payment, or data handling patterns 4. **Wait for both agents to complete** -5. **Combine findings** into a single report +5. **Automated vulnerability scan (optional):** + If ruflo-security-audit MCP tools are available (check for `mcp__claude-flow__security_scan` in available tools): + - Run `mcp__claude-flow__security_scan` with `--depth full` on the scoped files + - This adds CVE detection, shell injection scanning, and secrets-at-rest checks that the prompt-based agents above cannot perform + - Merge ruflo findings with CE agent findings. Deduplicate: same file:line from both sources -> keep the more detailed finding + - If ruflo is not installed, skip this step — CE agents provide sufficient coverage for threat modeling and OWASP +6. **Combine findings** into a single report ## Output Format @@ -82,7 +88,6 @@ Note areas that were reviewed and found clean — this provides confidence, not ## What This Skill Does NOT Do -- Does not replace static analysis tools (Snyk, SonarQube, npm audit) +- Does not replace static analysis tools (Snyk, SonarQube, npm audit) — though ruflo-security-audit adds partial CVE coverage when available - Does not run penetration tests or active exploitation -- Does not scan dependencies for known CVEs - Does not modify code — report only diff --git a/skills/ce-work/references/input-triage.md b/skills/ce-work/references/input-triage.md index 260d22830..29798ff24 100644 --- a/skills/ce-work/references/input-triage.md +++ b/skills/ce-work/references/input-triage.md @@ -24,6 +24,8 @@ This skill discovers plans under `/plans/`. Resolve `` when you firs **Session-state check comes first (standalone mode).** Before any input classification — including recovery activation below — check whether `SESSION_STATE.md` exists in the project root (`test -f SESSION_STATE.md`). If it exists, read it and read `references/session-state.md` for resume behavior, present the recorded state to the user, and ask whether to resume from it or start fresh; do not proceed to classification until the user responds. If it does not exist, continue. This local resume mechanism is distinct from the run-id recovery below (which targets external cross-model runs); do not conflate the two. In Return-to-Caller Mode the caller owns continuation state, so skip this check. +**Ruflo memory enrichment (optional, after the session-state check).** If `mcp__claude-flow__agentdb_health` is available in your tools, read `references/ruflo-memory-integration.md` and follow its session-start steps to query for related past sessions before classification. If ruflo is not available, skip this — `SESSION_STATE.md` is sufficient on its own. + **Recovery activation comes first.** Before normal plan, path, blank-input, or bare-prompt classification, interpret whether the user is semantically asking to resume, inspect status, reap, or clean up an existing external implementation run and has supplied its run id. This is intent recognition, not verb-only matching. Validate the id with the controller's safe-id contract: `^[A-Za-z0-9._-]{1,128}$` and at least one non-period character. When this direct recovery intent is present, read `references/cross-model-execution.md`, use that run id as authoritative for the requested controller operation, and return the observed state or blocker. Recovery must not dispatch a new worker, select a new route, fall through to latest-plan discovery, or run either shipping tail. When every unit is already cleaned, **completed recovery is read-only reconciliation**: Do not rerun test, build, format, install, generation, or `verify-run`; report the stored unit and plan-wide verification receipts. If recovery intent is clear but the run id is missing, request the id instead of guessing or classifying the text as new work. **Otherwise, parse a leading mode token.** If `` begins with `mode:return-to-caller` (or the legacy aliases `mode:caller-owned-tail` / `caller:lfg`), strip that token before anything else and enter **Return-to-Caller Mode** — implement and locally verify only, then return the structured envelope instead of running the standalone shipping tail. Before the plan path, accept up to two optional carriers in this fixed order: first one compact JSON object prefixed exactly `implementation_engine:`, then one run id prefixed exactly `implementation_run:`. Fully validate and normalize both before any workspace action. The engine object must contain exactly four fields: `mode` is `prefer` or `require`; `target` is `codex`, `claude`, `grok`, `cursor`, or `composer`; `model` is a string pin or `null`; and `source` is a non-empty caller-visible provenance string. The run carrier is accepted only for return-to-caller recovery and must satisfy the safe-id contract above. Reject malformed JSON, missing/extra fields, invalid field types or values, an unsafe run id, an out-of-order carrier, or a duplicate carrier. The entire remaining string is the plan path. A mode token or carrier with no following path is an error; report it instead of treating control data as a bare prompt. Without either optional carrier, the original `mode:return-to-caller ` form is unchanged and standing configuration remains eligible. diff --git a/skills/ce-work/references/ruflo-memory-integration.md b/skills/ce-work/references/ruflo-memory-integration.md new file mode 100644 index 000000000..5b0fbc98c --- /dev/null +++ b/skills/ce-work/references/ruflo-memory-integration.md @@ -0,0 +1,59 @@ +# Ruflo Memory Integration (Optional) + +Load this reference when `/ce-work` detects that ruflo-agentdb MCP tools are available. This enhances session resume with semantic recall from past sessions and stores task completion trajectories for future retrieval. + +This is an **optional enhancement** — if ruflo is not installed or the MCP server is not running, SESSION_STATE.md provides full session state persistence on its own. + +## Detection + +Before using any ruflo tools, check availability: + +1. Check if the tool `mcp__claude-flow__agentdb_health` exists in your available tools +2. If it does not exist, skip all ruflo integration — SESSION_STATE.md is sufficient +3. If it exists, call `mcp__claude-flow__agentdb_health` — if it returns an error, skip ruflo integration + +## At Session Start (after reading SESSION_STATE.md) + +After the SESSION_STATE.md check in Phase 0, if ruflo-agentdb is available: + +1. Extract the plan goal or work description from SESSION_STATE.md (or from the bare prompt if no state file exists) +2. Call `mcp__claude-flow__agentdb_pattern-search` with the goal/description as the query +3. If relevant past patterns are found, present them briefly: + > "Found [N] related past sessions in AgentDB. Key learnings: [one-line summary per pattern]" +4. Do not block on this — if the search is slow or returns nothing, proceed normally +5. This supplements SESSION_STATE.md, never replaces it. SESSION_STATE.md has the authoritative task progress; agentdb has cross-session context. + +## At Task Completion + +After updating SESSION_STATE.md at a task boundary, if ruflo-agentdb is available: + +1. Store a task summary to agentdb: + ``` + Tool: mcp__claude-flow__agentdb_hierarchical-store + Args: + key: "{branch}/{plan-filename}/{unit-id}" + value: "Goal: {unit goal}. Approach: {what was done}. Outcome: {success/failure/partial}." + namespace: "ce-task-completions" + ``` + +2. If the task involved a non-obvious solution (unexpected approach, workaround, or recovery from a failed first attempt), also store the pattern: + ``` + Tool: mcp__claude-flow__agentdb_pattern-store + Args: + pattern: "{description of the approach that worked and why}" + namespace: "ce-patterns" + ``` + +3. Keep storage lightweight — one call per task boundary, not per file change. + +## What NOT to Store + +- Routine task completions where the approach was obvious (followed existing pattern, no surprises) +- File contents or diffs (too large, too noisy) +- Temporary state that SESSION_STATE.md already captures (current task progress, blockers) + +## Failure Handling + +- If any ruflo MCP call fails, log the failure silently and continue — ruflo is a nice-to-have, not a dependency +- Never block ce-work execution waiting for ruflo +- Never retry failed ruflo calls — move on diff --git a/skills/ce-work/references/shipping-workflow.md b/skills/ce-work/references/shipping-workflow.md index 53aa76a9b..48daae140 100644 --- a/skills/ce-work/references/shipping-workflow.md +++ b/skills/ce-work/references/shipping-workflow.md @@ -70,6 +70,7 @@ This file contains the shipping workflow (Phase 3-4). It is loaded when all Phas - No console errors or warnings - If the plan has a `Requirements` section (or legacy `Requirements Trace`), verify each requirement is satisfied by the completed work - If any `Deferred to Implementation` questions were noted, confirm they were resolved during execution + - **Trajectory capture (conditional):** If the execution involved a non-obvious approach — an initial attempt that failed, an unexpected dependency order, or a workaround for a framework limitation — read `references/trajectory-capture.md` and write a trajectory doc. Skip this for routine work where the plan was followed with no surprises. 6. **Prepare Operational Validation Plan** (REQUIRED) - Add a `## Post-Deploy Monitoring & Validation` section to the PR description for every change. diff --git a/skills/ce-work/references/subagent-templates.md b/skills/ce-work/references/subagent-templates.md index 6c18060e9..02f1dc131 100644 --- a/skills/ce-work/references/subagent-templates.md +++ b/skills/ce-work/references/subagent-templates.md @@ -113,6 +113,21 @@ Use the least powerful model that can handle each role to conserve cost and incr **Heuristic:** If the plan unit has a complete spec with exact file paths, test scenarios, and patterns to follow — it's mechanical. If it requires the agent to make design decisions — use a more capable model. +### Model Selection Scoring + +When the task type isn't immediately obvious, score these signals to decide: + +| Signal | Fast/cheap (Haiku) | Standard (Sonnet) | Most capable (Opus) | +|--------|-------------------|-------------------|---------------------| +| **File count** | 1-2 files | 3-8 files | 9+ files | +| **Test complexity** | Unit tests only | Integration tests | Cross-service or E2E tests | +| **Domain** | Config, styling, renaming, docs | Business logic, API endpoints, UI components | Auth, payments, migrations, data integrity | +| **Pattern availability** | Exact pattern exists to copy | Similar pattern exists to adapt | Novel implementation required | +| **Execution note** | None or "trivial" | Standard | "Complex", "cross-cutting", or security-related | +| **Error handling** | No failure modes | Known failure modes | Distributed failures, partial rollback | + +**Scoring:** Default to Standard (Sonnet). Upgrade to Most capable (Opus) when 2+ signals point to it. Downgrade to Fast/cheap (Haiku) when all signals point to mechanical work with an exact pattern to follow. + ## Per-Task Review Pipeline After each subagent completes with DONE status: diff --git a/skills/ce-work/references/trajectory-capture.md b/skills/ce-work/references/trajectory-capture.md new file mode 100644 index 000000000..ba0691211 --- /dev/null +++ b/skills/ce-work/references/trajectory-capture.md @@ -0,0 +1,65 @@ +# Trajectory Capture + +Load this reference after shipping a feature (Phase 3-4) when the execution involved a non-obvious approach — an initial attempt that failed, an unexpected dependency order, or a workaround for a framework limitation. + +## Purpose + +Capture execution trajectories as human-readable markdown so future sessions (and future engineers) can learn from what was tried and what worked. This is complementary to the CE artifact root's `solutions/` tree (which captures post-hoc learnings about specific problems) — trajectories capture the **execution path**, not just the solution. + +## When to Capture + +Capture a trajectory when any of these are true: + +- The initial approach failed and a different one succeeded +- The execution order mattered (doing X before Y prevented issues) +- A framework limitation required a workaround +- A plan assumption turned out to be wrong, requiring adaptation +- The task took significantly longer than expected due to a non-obvious blocker + +Do NOT capture trajectories for routine work where the plan was followed directly with no surprises. + +## Format + +Write the trajectory under the CE artifact root's `solutions/{category}/` tree — the same location `/ce-work` already resolves for learnings — using the project's existing solution-doc conventions. If no such directory exists, write to the project root as a markdown file and let the engineer decide where to put it. + +```markdown +--- +date: YYYY-MM-DD +topic: {slug} +category: {developer-experience|integration-issues|build-errors|database-issues} +trajectory: true +--- + +# {Problem title} + +## What we were trying to do +{Plan goal, unit being implemented, and expected approach} + +## What we tried first +{Initial approach — what was done and what went wrong} +{Be specific: error messages, unexpected behavior, the moment it became clear this wasn't working} + +## What worked +{Final approach with enough detail to reproduce} +{Include file paths, key code patterns, and configuration that mattered} + +## Why this order mattered +{If execution sequence was critical, explain the dependency chain} +{Example: "The migration had to run before the seed script because..."} + +## Key files +{List the files that were central to the solution} + +## Time cost +{Optional: how long the detour took, to calibrate future estimates} +``` + +## How This Gets Used + +- The learnings-researcher review persona searches the `solutions/` tree by frontmatter metadata — the `trajectory: true` field lets it specifically find execution trajectories +- Future `/ce-work` sessions benefit when the learnings-researcher surfaces a relevant trajectory before implementation starts +- If ruflo-agentdb is available, the trajectory summary is also stored as a pattern for semantic search (see `ruflo-memory-integration.md`) + +## Orchestrator Responsibility + +The orchestrating `/ce-work` session decides whether to capture a trajectory. Subagents do not write trajectories — they report their outcomes (including failures and pivots) to the orchestrator, which has the full picture of the execution path.