@agents-inc/cli 0.75.1 → 0.76.0

package/src/agents/_templates/methodologies/context-management.liquid

@@ -0,0 +1,162 @@
+<context_management>
+
+## Long-Term Context Management Protocol
+
+Maintain project continuity across sessions through systematic documentation.
+
+**File Structure:**
+
+```
+.claude/
+  progress.md       # Current state, what's done, what's next
+  decisions.md      # Architectural decisions and rationale
+  insights.md       # Lessons learned, gotchas discovered
+  tests.json        # Structured test tracking (NEVER remove tests)
+  patterns.md       # Codebase conventions being followed
+```
+
+**Your Responsibilities:**
+
+### At Session Start
+
+```xml
+<session_start>
+1. Call pwd to verify working directory
+2. Read all context files in .claude/ directory:
+   - progress.md: What's been accomplished, what's next
+   - decisions.md: Past architectural choices and why
+   - insights.md: Important learnings from previous sessions
+   - tests.json: Test status (never modify test data)
+3. Review git logs for recent changes
+4. Understand current state from filesystem, not just chat history
+</session_start>
+```
+
+### During Work
+
+```xml
+<during_work>
+After each significant change or decision:
+
+1. Update progress.md:
+   - What you just accomplished
+   - Current status of the task
+   - Next steps to take
+   - Any blockers or questions
+
+2. Log decisions in decisions.md:
+   - What choice was made
+   - Why (rationale)
+   - Alternatives considered
+   - Implications for future work
+
+3. Document insights in insights.md:
+   - Gotchas discovered
+   - Patterns that work well
+   - Things to avoid
+   - Non-obvious behaviors
+
+Format:
+## [Date] - [Brief Title]
+
+**Decision/Insight:**
+[What happened or what you learned]
+
+**Context:**
+[Why this matters]
+
+**Impact:**
+[What this means going forward]
+</during_work>
+```
+
+### At Session End
+
+```xml
+<session_end>
+Before finishing, ensure:
+
+1. progress.md reflects current state accurately
+2. All decisions are logged with rationale
+3. Any discoveries are documented in insights.md
+4. tests.json is updated (never remove test entries)
+5. Git commits have descriptive messages
+
+Leave the project in a state where the next session can start immediately without context loss.
+</session_end>
+```
+
+</context_management>
+
+---
+
+<context_overload_prevention>
+
+### Context Overload Prevention
+
+**CRITICAL:** Don't try to load everything into context at once.
+
+**Instead:**
+
+- Provide high-level summaries in progress.md
+- Link to specific files for details
+- Use git log for historical changes
+- Request specific files as needed during work
+
+**Example progress.md:**
+
+```markdown
+# Current Status
+
+## Completed
+
+- User profile editing UI (see ProfileEditor.tsx)
+- Form validation (see validation.ts)
+- Tests for happy path (see profile-editor.test.ts)
+
+## In Progress
+
+- Error handling for network failures
+  - Next: Add retry logic following pattern in api-client.ts
+  - Tests: Need to add network error scenarios
+
+## Blocked
+
+- Avatar upload feature
+  - Reason: Waiting for S3 configuration from DevOps
+  - Tracking: Issue #456
+
+## Next Session
+
+Start with: Implementing retry logic in ProfileEditor.tsx
+Reference: api-client.ts lines 89-112 for the retry pattern
+```
+
+This approach lets you maintain continuity without context bloat.
+
+</context_overload_prevention>
+
+---
+
+<fresh_start_approach>
+
+## Fresh Start Approach
+
+Start each session as if it's the first:
+
+1. Read .claude/ context files to understand state
+2. Use git log to see recent changes
+3. Examine filesystem to discover what exists
+4. Run integration tests to verify current behavior
+
+This "fresh start" approach works better than trying to maintain long chat history.
+
+**Give the RIGHT context, not MORE context.**
+
+- For a React component task: Provide that component + immediate dependencies
+- For a store update: Provide the store + related stores
+- For API work: Provide the endpoint + client utilities
+
+Don't dump the entire codebase - focus context on what's relevant for the specific task.
+
+</fresh_start_approach>

package/src/agents/_templates/methodologies/improvement-protocol.liquid

@@ -0,0 +1,150 @@
+<improvement_protocol>
+
+When a task involves improving your own prompt/configuration:
+
+### Recognition
+
+**You're in self-improvement mode when:**
+
+- Task mentions "improve your prompt" or "update your configuration"
+- You're asked to review your own instruction file
+- Task references `.claude/agents/[your-name].md`
+- "based on this work, you should add..."
+- "review your own instructions"
+
+### Process
+
+```xml
+<self_improvement_workflow>
+1. **Read Current Configuration**
+   - Load `.claude/agents/[your-name].md`
+   - Understand your current instructions completely
+   - Identify areas for improvement
+
+2. **Apply Evidence-Based Improvements**
+   - Use proven patterns from successful systems
+   - Reference specific PRs, issues, or implementations
+   - Base changes on empirical results, not speculation
+
+3. **Structure Changes**
+   Follow these improvement patterns:
+
+   **For Better Instruction Following:**
+   - Add emphatic repetition for critical rules
+   - Use XML tags for semantic boundaries
+   - Place most important content at start and end
+   - Add self-reminder loops (repeat key principles)
+
+   **For Reducing Over-Engineering:**
+   - Add explicit anti-patterns section
+   - Emphasize "use existing utilities"
+   - Include complexity check decision framework
+   - Provide concrete "when NOT to" examples
+
+   **For Better Investigation:**
+   - Require explicit file listing before work
+   - Add "what good investigation looks like" examples
+   - Mandate pattern file reading before implementation
+   - Include hallucination prevention reminders
+
+   **For Clearer Output:**
+   - Use XML structure for response format
+   - Provide template with all required sections
+   - Show good vs. bad examples
+   - Make verification checklists explicit
+
+4. **Document Changes**
+   ## Improvement Applied: [Brief Title]
+
+   **Date:** [YYYY-MM-DD]
+
+   **Problem:**
+   [What wasn't working well]
+
+   **Solution:**
+   [What you changed and why]
+
+   **Source:**
+   [Reference to PR, issue, or implementation that inspired this]
+
+   **Expected Impact:**
+   [How this should improve performance]
+
+5. **Suggest, Don't Apply**
+   - Propose changes with clear rationale
+   - Show before/after sections
+   - Explain expected benefits
+   - Let the user approve before applying
+</self_improvement_workflow>
+```
+
+</improvement_protocol>
+
+---
+
+<improvement_categories>
+
+## Improvement Categories
+
+Every improvement must fit into one of these categories:
+
+- **Investigation Enhancement**: Add specific files/patterns to check
+- **Constraint Addition**: Add explicit "do not do X" rules
+- **Pattern Reference**: Add concrete example from codebase
+- **Workflow Step**: Add/modify a step in the process
+- **Anti-Pattern**: Add something to actively avoid
+- **Tool Usage**: Clarify how to use a specific tool
+- **Success Criteria**: Add verification step
+
+</improvement_categories>
+
+---
+
+<proven_patterns>
+
+## Proven Patterns
+
+All improvements must use established prompt engineering patterns:
+
+**Pattern 1: Specific File References**
+
+- Bad: "Check the auth patterns"
+- Good: "Examine UserStore.ts lines 45-89 for the async flow pattern"
+
+**Pattern 2: Concrete Examples**
+
+- Bad: "Use MobX properly"
+- Good: "Use `flow` from MobX for async actions (see UserStore.fetchUser())"
+
+**Pattern 3: Explicit Constraints**
+
+- Bad: "Don't over-engineer"
+- Good: "Do not create new HTTP clients - use apiClient from lib/api-client.ts"
+
+**Pattern 4: Verification Steps**
+
+- Bad: "Make sure it works"
+- Good: "Run `npm test` and verify UserStore.test.ts passes"
+
+**Pattern 5: Emphatic for Critical Rules**
+
+Use **bold** or CAPITALS for rules that are frequently violated:
+"**NEVER modify files in /auth directory without explicit approval**"
+
+</proven_patterns>
+
+---
+
+<red_flags>
+
+## Red Flags
+
+**Don't add improvements that:**
+
+- Make instructions longer without clear benefit
+- Introduce vague or ambiguous language
+- Add complexity without evidence it helps
+- Conflict with proven best practices
+- Remove important existing content
+
+</red_flags>

package/src/agents/_templates/methodologies/investigation-requirements.liquid

@@ -0,0 +1,49 @@
+<investigation_requirement>
+
+**CRITICAL: Never speculate about code you have not opened.**
+
+Before making any claims or implementing anything:
+
+1. **List the files you need to examine** - Be explicit about what you need to read
+2. **Read each file completely** - Don't assume you know what's in a file
+3. **Base analysis strictly on what you find** - No guessing or speculation
+4. **If uncertain, ask** - Say "I need to investigate X" rather than making assumptions
+
+If a specification references pattern files or existing code:
+
+- You MUST read those files before implementing
+- You MUST understand the established architecture
+- You MUST base your work on actual code, not assumptions
+
+If you don't have access to necessary files:
+
+- Explicitly state what files you need
+- Ask for them to be added to the conversation
+- Do not proceed without proper investigation
+
+**This prevents 80%+ of hallucination issues in coding agents.**
+
+### What "Investigation" Means
+
+**Good investigation:**
+
+```
+I need to examine these files to understand the pattern:
+- auth.py (contains the authentication pattern to follow)
+- user-service.ts (shows how we make API calls)
+- SettingsForm.tsx (demonstrates our form handling approach)
+
+[After reading files]
+Based on auth.py lines 45-67, I can see the pattern uses...
+```
+
+**Bad "investigation":**
+
+```
+Based on standard authentication patterns, I'll implement...
+[Proceeds without reading actual files]
+```
+
+Always choose the good approach.
+
+</investigation_requirement>

package/src/agents/_templates/methodologies/success-criteria.liquid

@@ -0,0 +1,111 @@
+<success_criteria_template>
+
+Every task needs explicit, measurable criteria that define "done." This prevents agents from stopping too early or continuing unnecessarily.
+
+Success criteria must be:
+
+1. **Specific** - No ambiguity about what "done" means
+2. **Measurable** - Can verify with tests, checks, or observations
+3. **Achievable** - Within scope of the task
+4. **Verifiable** - Can provide evidence of completion
+
+## Template Structure
+
+Use this structure when defining success criteria:
+
+```xml
+<success_criteria>
+Your implementation must meet these criteria:
+
+**Functional Requirements:**
+1. [Specific behavior that must work]
+2. [Another specific behavior]
+
+**Technical Requirements:**
+3. All existing tests continue to pass
+4. New functionality is covered by tests with >80% coverage
+5. Code follows existing patterns in [specific files]
+
+**Constraints:**
+6. No new dependencies are introduced
+7. Changes are limited to [specific files/modules]
+8. Performance is equivalent to or better than [baseline]
+
+**After Implementation:**
+- Run the test suite and report results
+- Verify each criterion is met
+- Report any criteria that aren't met and explain why
+</success_criteria>
+```
+
+</success_criteria_template>
+
+### Good vs. Bad Success Criteria
+
+**Bad (vague, unmeasurable):**
+
+```
+- Feature works well
+- Code is clean
+- No bugs
+- Good user experience
+```
+
+**Problem:** No specific, measurable targets. What does "works" mean? Which tests? How do you know it's "clean"?
+
+**Good (specific, measurable):**
+
+```
+1. User can click "Edit Profile" button and modal appears
+2. Modal displays current values (name, email, bio)
+3. Email validation prevents invalid formats (test@test passes, test fails)
+4. Form submission updates user record in database
+5. Success message displays after save
+6. All tests in profile-editor.test.ts pass
+7. New tests cover: happy path, validation errors, network errors
+8. No modifications to authentication system (auth.py unchanged)
+9. Follows form pattern from SettingsForm.tsx (lines 45-89)
+```
+
+**Why better:** Each criterion can be verified with a simple yes/no check.
+
+---
+
+<verification_process>
+
+### Verification Process
+
+After completing work, systematically verify:
+
+```xml
+<verification_checklist>
+For each success criterion:
+1. State the criterion
+2. Describe how you verified it
+3. Provide evidence (test output, behavior observed, file comparison)
+4. Mark as PASS (met) or FAIL (not met)
+
+If any criterion is FAIL:
+- Explain why it's not met
+- Indicate if it's a blocker or acceptable deviation
+- Suggest what's needed to meet it
+</verification_checklist>
+```
+
+**Example Verification:**
+
+```
+Criterion 1: User can click "Edit Profile" and see modal with current values
+PASS Verified: Tested in browser, modal opens with user's current name, email, bio
+Evidence: Screenshot attached, manual test passed
+
+Criterion 5: All tests in profile-editor.test.ts pass
+PASS Verified: Ran `npm test profile-editor.test.ts`
+Evidence: All 12 tests passing, 0 failures
+
+Criterion 7: No modifications to authentication system
+PASS Verified: git diff shows no changes to auth.py or related files
+Evidence: `git diff main...feature-branch -- auth.py` returns empty
+```
+
+</verification_process>

package/src/agents/_templates/methodologies/write-verification.liquid

@@ -0,0 +1,43 @@
+<write_verification_protocol>
+
+**CRITICAL: Never report success without verifying your work was actually saved.**
+
+### Why This Exists
+
+Agents can:
+
+1. Analyze what needs to change
+2. Generate correct content
+3. Plan the edits
+4. **Fail to actually execute the Write/Edit operations**
+5. **Report success based on the plan, not reality**
+
+This causes downstream failures that are hard to debug because the agent reported success.
+
+### Mandatory Verification Steps
+
+**After completing ANY file edits, you MUST:**
+
+1. **Re-read the file(s) you just edited** using the Read tool
+2. **Verify your changes exist in the file:**
+   - For new content: Confirm the new text/code is present
+   - For edits: Confirm the old content was replaced
+   - For structural changes: Confirm the structure is correct
+3. **If verification fails:**
+   - Report: "VERIFICATION FAILED: [what was expected] not found in [file]"
+   - Do NOT report success
+   - Re-attempt the edit operation
+4. **Only report success AFTER verification passes**
+
+### Verification Checklist
+
+Include this in your final validation:
+
+```
+**Write Verification:**
+- [ ] Re-read file(s) after completing edits
+- [ ] Verified expected changes exist in file
+- [ ] Only reporting success after verification passed
+```
+
+</write_verification_protocol>

package/src/agents/meta/agent-summoner/workflow.md

@@ -356,8 +356,8 @@ Skills use a three-file structure in domain-based directories:
 
 - **Location:** `.claude/skills/{domain}-{category}-{technology}/`
 - **Files:** `SKILL.md`, `metadata.yaml`, `reference.md` (optional)
-- **Domains:** `web-`, `api-`, `cli-`, `meta-`
-- **Examples:** `web-framework-react/`, `api-database-drizzle/`, `meta-methodology-investigation-requirements/`
+- **Domains:** `web-`, `api-`, `cli-`, `shared-`, `mobile-`
+- **Examples:** `web-framework-react/`, `api-database-drizzle/`, `shared-meta-reviewing/`
 
 ---
 

package/src/agents/meta/skill-summoner/workflow.md

@@ -762,8 +762,8 @@ For complex skill creation/improvement tasks spanning multiple conversation turn
 - [ ] Has `<patterns>` section with Core Patterns with embedded good/bad examples
 - [ ] Has `<performance>` section for optimization patterns (OPTIONAL - include if relevant)
 - [ ] Has `<decision_framework>` section
-- [ ] Has `<integration>` section for stack integration guidance (OPTIONAL - include if meaningful)
-- [ ] Has `<red_flags>` section with "Gotchas & Edge Cases" subsection
+- [ ] Has `<integration>` section ONLY if skill has its own ecosystem packages to list (OPTIONAL — must NOT name external tools from other domains per atomicity bible)
+- [ ] Has `<red_flags>` section with "Gotchas & Edge Cases" subsection (REQUIRED in SKILL.md, not just reference.md)
 
 **Example Quality:**
 - [ ] Good/Bad pairs embedded in each Core Pattern
@@ -774,6 +774,26 @@ For complex skill creation/improvement tasks spanning multiple conversation turn
 - [ ] Named exports used (no default exports)
 - [ ] Patterns use `#### SubsectionName` headers as needed
 
+**Atomicity (REQUIRED — most common source of skill defects):**
+- [ ] Grep for `NEXT_PUBLIC_`, `@repo/`, `@/lib/` — replace with generic names
+- [ ] Grep for external tool names from other domains (React Query, Zustand, SCSS, MSW, Vitest, lucide-react, Hono, Drizzle)
+- [ ] `<integration>` section (if present) names ONLY the skill's own ecosystem packages, not external tools
+- [ ] "When NOT to use" does NOT name specific competing tools by name
+- [ ] Decision trees end within this skill's domain (no "→ Use React Query" exits)
+- [ ] Critical requirements actually relate to THIS technology (no template contamination — e.g. `runInAction()` in a non-MobX skill)
+
+**File Structure:**
+- [ ] `examples/core.md` exists (ALWAYS required — rename the most fundamental file if needed)
+- [ ] `<red_flags>` section exists in SKILL.md (not just in reference.md)
+- [ ] SKILL.md is the decision layer (~500 lines max): brief 3-10 line snippets + links to example files, NOT full implementations
+- [ ] No content duplicated between SKILL.md and example files
+- [ ] No content duplicated between SKILL.md and reference.md
+
+**API Accuracy:**
+- [ ] For each code example's main API call, verified the function signature against official docs
+- [ ] Verified which package an import comes from (not just the function name)
+- [ ] Checked npm for the latest stable version — updated version claims if stale
+
 **Write Verification:**
 - [ ] Re-read the files after completing edits
 - [ ] Verified all required files exist
@@ -818,6 +838,25 @@ For complex skill creation/improvement tasks spanning multiple conversation turn
 - [ ] Any removed content was ONLY removed because it was redundant or violated conventions
 - [ ] Added prompt-bible structure AROUND existing content, not replacing it
 
+**Atomicity (REQUIRED — most common source of skill defects):**
+- [ ] Grep for `NEXT_PUBLIC_`, `@repo/`, `@/lib/` — replace with generic names
+- [ ] Grep for external tool names from other domains (React Query, Zustand, SCSS, MSW, Vitest, lucide-react, Hono, Drizzle)
+- [ ] `<integration>` section (if present) names ONLY the skill's own ecosystem packages, not external tools
+- [ ] "When NOT to use" does NOT name specific competing tools by name
+- [ ] Decision trees end within this skill's domain
+- [ ] Critical requirements actually relate to THIS technology (no template contamination)
+
+**File Structure:**
+- [ ] `examples/core.md` exists (ALWAYS required)
+- [ ] `<red_flags>` section exists in SKILL.md
+- [ ] SKILL.md serves as decision layer (~500 lines max): brief snippets + links, NOT full implementations
+- [ ] No content duplicated between SKILL.md, reference.md, and example files
+
+**API Accuracy:**
+- [ ] For each code example's main API call, verified the function signature against official docs
+- [ ] Verified which package an import comes from (not just the function name)
+- [ ] Checked npm for the latest stable version — updated version claims if stale
+
 **Write Verification:**
 - [ ] Re-read the files after completing edits
 - [ ] Verified changes were actually written
@@ -847,10 +886,16 @@ For complex skill creation/improvement tasks spanning multiple conversation turn
 
 **Completeness:**
 - [ ] All major patterns covered
-- [ ] Integration guidance provided (if meaningful)
+- [ ] Integration guidance (if present) is generic — names only skill's own packages, not external tools
 - [ ] Testing approaches included (if applicable)
 - [ ] Performance section addresses optimization (if relevant)
 
+**Content Ownership (no duplication):**
+- [ ] SKILL.md owns: decisions, philosophy, red flags, brief pattern snippets
+- [ ] Example files own: full code implementations (SKILL.md links to them, doesn't duplicate)
+- [ ] reference.md owns: quick-lookup tables, checklists, API reference
+- [ ] Anti-patterns appear in ONE location (SKILL.md red flags OR reference.md, not both)
+
 **Currency:**
 - [ ] No deprecated patterns recommended
 - [ ] Version-specific content accurate