AGENTS.md

1# AGENTS
2 
3## Start of Session
4 
5- Read SOUL.md to align identity.
6- Read TOOLS.md for available commands and skills.
7- Review the team shared doc (TEAM.md) for the priority framework and methodology.
8 
9## Primary Workflow: Priority Waterfall
10 
11Work through priorities P1 to P5 in order. Stop at the highest level that needs attention. Do not skip ahead to lower priorities when higher ones have active issues.
12 
13### P1 — Core Infrastructure Health
14 
15Check whether Vrooli's foundational infrastructure is healthy.
16 
171. Run `vrooli-autoheal status --json` to get current health.
182. If any checks are **critical** or **failing**:
19   - Assess blast radius (which scenarios and resources are affected).
20   - Escalate to director-swarm with severity, affected systems, and recommended action.
21   - Do not proceed to P2-P5 until the issue is resolved or acknowledged.
223. If all checks are healthy, proceed to P2.
23 
24### P2 — Critical Toolchain Issues
25 
26Check whether development tools and steer skills are producing correct, non-contradictory output.
27 
281. Run `development-toolchain-validator validate <reference>` for each registered reference.
292. Check `development-toolchain-validator report --conflicts` for cross-skill contradictions.
303. Check `scenario-auditor scan <scenario> --summary` for critical violations on key scenarios.
314. If **conflicts** or **critical violations** are found:
32   - Skill conflicts: assign to skill-optimizer with conflict details and both skills identified.
33   - Tool failures: escalate to ecosystem-manager for tool repair.
34   - Do not proceed to lower priorities until critical items are assigned or escalated.
355. If no critical issues, proceed to P3.
36 
37### P3 — Toolchain Degradation
38 
39Check for non-urgent but high-leverage quality erosion.
40 
411. Run `development-toolchain-validator report --drift` for skills that changed since last validation.
422. Run `development-toolchain-validator report --maturity` for skills too vague to validate programmatically.
433. Run `development-toolchain-validator report --tool-baselines` for tool accuracy regressions.
444. Queue findings for skill-optimizer (drift, maturity) or escalation (tool regressions).
455. Proceed to P4.
46 
47### P4 — Skill/Agent/Team Health
48 
49The team's core optimization work. Use the relationship graph to find concrete targets.
50 
511. Run `prompt-manager graph show` for overall health delta since last check.
522. Run `prompt-manager graph health` to identify entities with low or declining health.
533. Run structural queries to surface issues:
54   - `prompt-manager graph orphaned-skills` — unreferenced skills.
55   - `prompt-manager graph skillless-agents` — agents missing skill references.
56   - `prompt-manager graph empty-teams` — teams without members.
57   - `prompt-manager graph cliless-skills` — CLI promotion candidates.
58   - `prompt-manager graph circular-refs` — dependency cycles.
594. Cross-reference `prompt-manager graph popular --type skill` with health scores to find high-leverage targets (widely used but low health).
605. Use `prompt-manager graph node <id>` to inspect specific entities before assigning work.
616. Assign optimization work to the appropriate specialist:
62   - Skill issues go to skill-optimizer.
63   - Agent issues go to agent-optimizer.
64   - Team issues go to team-optimizer.
65 
66### P5 — Opportunities
67 
68Growth work when P1-P4 have no active issues.
69 
701. Review DTV coverage gaps (skills connected but lacking expectations).
712. Analyze cross-team feedback for capability gaps.
723. Feed identified opportunities into the Research-Analyze-Plan pipeline:
73   `prompt-manager skill read leader-research-analyze-plan`
744. Use `prompt-manager skill read capability-extraction` to audit agent files for extractable methodologies.
75 
76## When to Use Other Skills Directly
77 
78- **Single skill needs improvement** — Use `skill-improvement-suggestions` directly without pipeline overhead.
79- **Agent files are bloated or contain duplicated patterns** — Use `capability-extraction` to audit agent files. Extraction specs feed into `leader-research-analyze-plan` for ecosystem integration planning.
80- **Friction analysis on a conversation** — Use `conversation-friction-analysis` directly (output can feed into the pipeline as a research input).
81- **Known implementation work** — Use `leader-explore-plan-implement`.
82- **Bug fixing** — Use `leader-triage-investigate-resolve`.
83 
84## Coordination
85 
86- Assign optimization work to team members via team inbox.
87- Escalate P1/P2 issues to director-swarm.
88- Escalate tool fixes to ecosystem-manager.
89- Report improvements to director-swarm.
90- Share new or improved skills with all teams that can benefit.
91- Track progress on active optimization cycles using `prompt-manager skill read visited-tracker-tools`.
92