@massa-ai/codex-plugin 1.26.0 → 1.29.0

package/skills/massa-ai/references/skill-architect/patterns.md

@@ -0,0 +1,317 @@
+# Skill Patterns Reference
+
+This document details the five proven patterns for skill architecture.
+Read this when deciding how to structure a skill's workflow during the
+Architecture phase.
+
+## Table of Contents
+
+1. Sequential Workflow Orchestration (line ~20)
+2. Multi-MCP Coordination (line ~70)
+3. Iterative Refinement (line ~120)
+4. Context-Aware Tool Selection (line ~170)
+5. Domain-Specific Intelligence (line ~210)
+6. Choosing Between Patterns (line ~250)
+7. Combining Patterns (line ~280)
+
+---
+
+## 1. Sequential Workflow Orchestration
+
+**Use when:** Users need multi-step processes executed in a specific order,
+where each step depends on the previous one.
+
+**Problem-first framing:** "I need to onboard a new customer" → Skill
+orchestrates the right calls in the right sequence.
+
+**Key characteristics:**
+
+- Explicit step ordering with dependencies between steps
+- Validation gates between steps (don't proceed if step N fails)
+- Rollback instructions for failures
+- Data flows from earlier steps to later ones
+
+**Structure template:**
+
+```markdown
+## Workflow: [Name]
+
+### Step 1: [Action]
+Call tool: `tool_name`
+Parameters: [what's needed]
+Validation: [how to know it succeeded]
+On failure: [what to do]
+
+### Step 2: [Action]
+Depends on: Step 1 (uses [specific output])
+Call tool: `tool_name`
+Parameters: [include output from Step 1]
+Validation: [check]
+
+### Step 3: [Action]
+...
+```
+
+**When to choose this pattern:**
+
+- The workflow has a natural linear order
+- Steps have clear dependencies
+- Skipping a step would break the workflow
+- Users currently do these steps manually in sequence
+
+**Watch out for:**
+
+- Rigid ordering when some steps could be parallel
+- Missing rollback logic (what if step 3 fails after step 1 and 2 succeeded?)
+- Not validating between steps
+
+---
+
+## 2. Multi-MCP Coordination
+
+**Use when:** Workflows span multiple external services, each connected
+via its own MCP server.
+
+**Key characteristics:**
+
+- Clear phase separation by service
+- Data passing between MCP servers
+- Validation before moving to next phase
+- Centralized error handling across services
+
+**Structure template:**
+
+```markdown
+## Workflow: [Name]
+
+### Phase 1: [Service A] ([MCP name])
+1. [Action using Service A tools]
+2. [Action using Service A tools]
+Output: [data needed by Phase 2]
+
+### Phase 2: [Service B] ([MCP name])
+Input: [data from Phase 1]
+1. [Action using Service B tools]
+2. [Action using Service B tools]
+Output: [data needed by Phase 3]
+
+### Phase 3: [Service C] ([MCP name])
+...
+
+## Error Handling
+- If Phase 1 fails: [action]
+- If Phase 2 fails but Phase 1 succeeded: [action]
+```
+
+**When to choose this pattern:**
+
+- The workflow crosses service boundaries
+- Multiple MCP servers are involved
+- Data needs to flow between services
+- Users currently switch between tools manually
+
+**Watch out for:**
+
+- Assuming all MCPs are connected (check availability first)
+- Not handling partial failures (Phase 2 fails but Phase 1 already ran)
+- Tight coupling between phases (prefer passing data explicitly)
+
+---
+
+## 3. Iterative Refinement
+
+**Use when:** Output quality improves through multiple review-and-fix cycles.
+
+**Key characteristics:**
+
+- Initial draft generation
+- Quality check against explicit criteria
+- Refinement loop with clear stopping conditions
+- Finalization step
+
+**Structure template:**
+
+```markdown
+## Workflow: [Name]
+
+### Initial Draft
+1. Gather input data
+2. Generate first version
+3. Save to working file
+
+### Quality Check
+Run validation: `scripts/[check_quality].py`
+Criteria:
+- [Criterion 1]: [how to check]
+- [Criterion 2]: [how to check]
+- [Criterion 3]: [how to check]
+
+### Refinement Loop
+For each issue found:
+1. Identify the specific problem
+2. Fix it
+3. Re-validate
+
+STOP when:
+- All criteria pass, OR
+- 3 iterations completed (diminishing returns), OR
+- User signals satisfaction
+
+### Finalization
+1. Apply final formatting
+2. Generate summary of changes
+3. Save final version
+```
+
+**When to choose this pattern:**
+
+- Output quality is subjective or multi-dimensional
+- First drafts are usually "close but not quite"
+- Users currently review and ask for revisions manually
+- There are explicit quality criteria to check against
+
+**Watch out for:**
+
+- Infinite loops (always define stopping conditions)
+- Over-polishing (3 iterations is usually enough)
+- Vague quality criteria (make them checkable)
+
+---
+
+## 4. Context-Aware Tool Selection
+
+**Use when:** The same goal can be achieved with different tools depending
+on the input or context.
+
+**Key characteristics:**
+
+- Decision tree based on input properties
+- Fallback options when primary choice isn't available
+- Transparency about why a particular path was chosen
+
+**Structure template:**
+
+```markdown
+## Workflow: [Name]
+
+### Analyze Input
+Check: [what properties to examine]
+- Property A: [value range or type]
+- Property B: [value range or type]
+
+### Decision Tree
+IF [condition 1]:
+  → Use [Tool/Approach A]
+  Rationale: [why this is better for this case]
+ELIF [condition 2]:
+  → Use [Tool/Approach B]
+  Rationale: [why]
+ELSE:
+  → Use [Tool/Approach C] (default)
+
+### Execute
+Based on decision, execute using the selected approach.
+
+### Explain Choice
+Tell the user which approach was selected and why.
+```
+
+**When to choose this pattern:**
+
+- Multiple valid approaches exist for the same goal
+- The "best" approach depends on input characteristics
+- Users don't know (or shouldn't need to know) which tool is optimal
+
+**Watch out for:**
+
+- Decision criteria that overlap (ambiguous routing)
+- Missing fallback for edge cases
+- Not explaining the choice to the user
+
+---
+
+## 5. Domain-Specific Intelligence
+
+**Use when:** The skill's value comes from specialized knowledge, not just
+tool orchestration.
+
+**Key characteristics:**
+
+- Domain rules and constraints embedded in logic
+- Compliance or validation checks before action
+- Comprehensive audit trails
+- Expert-level decision making
+
+**Structure template:**
+
+```markdown
+## Workflow: [Name]
+
+### Pre-Check ([Domain] Rules)
+Before proceeding, verify:
+1. [Domain rule 1]: [how to check]
+2. [Domain rule 2]: [how to check]
+3. [Domain rule 3]: [how to check]
+
+IF any rule fails:
+  → [Escalation or alternative path]
+  → Document the failure
+
+### Execute
+Only if pre-checks pass:
+1. [Action with domain context]
+2. [Action with domain context]
+
+### Audit Trail
+Log:
+- All checks performed and results
+- Decisions made and rationale
+- Actions taken
+```
+
+**When to choose this pattern:**
+
+- The skill needs expert knowledge to execute correctly
+- There are compliance, safety, or quality rules to enforce
+- Getting it wrong has significant consequences
+- Users benefit from the skill's "expertise" more than its automation
+
+**Watch out for:**
+
+- Outdated domain knowledge (plan for updates)
+- Over-encoding rules that change frequently (reference external docs instead)
+- Not documenting the reasoning for decisions
+
+---
+
+## 6. Choosing Between Patterns
+
+| Signal | Suggested Pattern |
+|--------|------------------|
+| "Do A, then B, then C" | Sequential Workflow |
+| "Get data from X, send to Y, notify in Z" | Multi-MCP Coordination |
+| "Make it good, then review and improve" | Iterative Refinement |
+| "Handle PDFs differently from CSVs" | Context-Aware Selection |
+| "Follow our compliance rules" | Domain-Specific Intelligence |
+| Steps have no dependencies | Consider parallel execution |
+| User says "it depends" a lot | Context-Aware Selection |
+| Quality is subjective | Iterative Refinement |
+
+---
+
+## 7. Combining Patterns
+
+Most real skills combine patterns. Common combinations:
+
+- **Sequential + Domain Intelligence:** Follow steps in order, but embed
+  expert checks at critical points (e.g., compliance check before payment)
+- **Multi-MCP + Iterative:** Coordinate across services, then refine the
+  combined output
+- **Context-Aware + Sequential:** Choose the right tool first, then follow
+  a sequential workflow specific to that tool
+- **Domain Intelligence + Iterative:** Apply domain rules, generate output,
+  review against domain criteria, refine
+
+When combining, identify the PRIMARY pattern (the one that shapes the
+overall flow) and SECONDARY patterns (the ones that apply within specific
+steps).

package/skills/massa-ai/references/skill-architect/quality-checklist.md

@@ -0,0 +1,70 @@
+# Quality Checklist
+
+Use this checklist at the end of the Validate phase to ensure the skill
+meets all quality criteria before delivery.
+
+---
+
+## Structural Checks (Pass/Fail)
+
+These are hard requirements. Any failure must be fixed.
+
+- [ ] SKILL.md exists with exact casing
+- [ ] YAML frontmatter has opening and closing `---` delimiters
+- [ ] `name` field is present and kebab-case
+- [ ] `name` matches the folder name
+- [ ] `description` field is present
+- [ ] `description` is under 1024 characters
+- [ ] `description` contains no XML angle brackets (< >)
+- [ ] `name` does not contain "claude" or "anthropic"
+- [ ] No README.md inside the skill folder
+- [ ] Folder name is kebab-case (no spaces, no capitals, no underscores)
+
+## Description Quality (Score 1-5)
+
+Rate each and target 4+ on all:
+
+- [ ] **Specificity (1-5):** Does it describe a concrete capability?
+- [ ] **Trigger clarity (1-5):** Would the agent know when to load this?
+- [ ] **User language (1-5):** Does it use phrases a user would actually say?
+- [ ] **Scope boundaries (1-5):** Is it clear what this skill does NOT do?
+- [ ] **Pushiness (1-5):** Is it assertive enough to avoid undertriggering?
+
+## Instruction Quality (Score 1-5)
+
+- [ ] **Actionability (1-5):** Can the agent follow every step without ambiguity?
+- [ ] **Specificity (1-5):** Are instructions concrete (not "validate properly")?
+- [ ] **Examples (1-5):** Are there realistic input/output examples?
+- [ ] **Error handling (1-5):** Are common failures addressed?
+- [ ] **Progressive disclosure (1-5):** Is SKILL.md focused, with details in refs?
+- [ ] **Composability (1-5):** Does it play well with other skills?
+
+## Trigger Testing
+
+### Should trigger (test 3-5 phrases)
+
+1. [ ] "[Obvious request]" → triggers? Y/N
+2. [ ] "[Paraphrased request]" → triggers? Y/N
+3. [ ] "[Informal request]" → triggers? Y/N
+
+### Should NOT trigger (test 3-5 phrases)
+
+1. [ ] "[Unrelated task]" → stays silent? Y/N
+2. [ ] "[Similar but different scope]" → stays silent? Y/N
+3. [ ] "[Generic question]" → stays silent? Y/N
+
+## Performance Targets
+
+Aspirational benchmarks (adapt to your skill):
+
+- [ ] Triggers on ≥90% of relevant queries
+- [ ] Completes workflow without user correction
+- [ ] Consistent results across separate sessions
+- [ ] No failed tool/API calls per workflow
+- [ ] Users don't need to prompt the agent about next steps
+
+## Final Sign-Off
+
+- [ ] User has reviewed the skill
+- [ ] Test phrases produce expected behavior
+- [ ] Skill is packaged and ready for upload

package/skills/massa-ai/references/sonarqube-mcp.md

@@ -0,0 +1,73 @@
+# SonarQube MCP Protocol
+
+Use from `workflows/implementation/implementation-audit.md` and
+`workflows/implementation/implementation-fix.md` when SonarQube MCP tools may
+be available for the current implementation scope.
+
+## Detection And Availability
+
+Check whether SonarQube MCP is available and useful for the implementation
+scope:
+
+- Detect callable SonarQube MCP tools at runtime, such as project discovery,
+  issue search, file/snippet analysis, advanced code analysis, duplicated-file
+  search, component measures, security hotspots, guidelines, or quality gate
+  status.
+- If SonarQube MCP is unavailable, no project key can be resolved, required
+  credentials/configuration are missing, or the target files are outside the
+  configured SonarQube project, record `SonarQube MCP: not evaluated` with the
+  skipped-check reason and continue normal lens synthesis.
+
+## Firewall And Invocation
+
+If available, use `references/context-firewall.md` and pass only the
+immutable implementation scope packet, resolved files, branch/PR identifiers,
+project key, and minimal file contents or paths the selected SonarQube tools
+require.
+
+Wait for SonarQube MCP execution to finish when a tool starts analysis,
+capture quality gate status when available, and summarize raw
+issues/measures/hotspots instead of copying raw tool output into the report.
+
+## Normalization Areas
+
+Normalize actionable SonarQube results into only these implementation audit
+areas: Architecture, Correctness/Bugs, Code Quality, Security, and Tests. Do
+not create a Requirements finding from SonarQube output.
+
+## Preserved Fields
+
+Preserve Sonar issue key, rule key, tool name, severity/impact, file/line,
+quality gate condition, and evidence summary inside the normalized finding.
+
+## ID Mapping
+
+Use normal source-qualified implementation IDs after normalization, such as
+`Architecture/ARCH-1`, `Correctness/BUG-1`, `Code Quality/CQ-1`,
+`Security/SEC-1`, or `Tests/TST-1`; do not invent `SONAR-*` executable finding
+IDs. The canonical area/prefix table and discipline live in
+`references/audit-report-io.md` (Source-Qualified Finding IDs).
+
+## Exclusion Rules
+
+Keep unmapped, duplicate, low-context, or out-of-scope SonarQube results in
+Scope And Evidence or skipped checks, not in Findings or Execution Handoff.
+
+## Reporting Integration
+
+- Include SonarQube MCP as evidence in the coverage matrix or Scope And
+  Evidence, with quality gate status when available.
+- Sonar-derived findings enter the execution handoff only after normalization
+  to one supported source lens ID, with enough evidence for
+  `implementation-fix` to revalidate from the saved markdown report.
+- Do not persist raw SonarQube output; persist only normalized, durable
+  patterns after Importance Calibration.
+
+## Fix-Time Consumption
+
+Treat SonarQube-derived items as actionable only when the saved
+implementation report already normalized them to a supported source-qualified
+ID with source lens, original ID, Sonar issue/rule evidence, location,
+impact, and verification suggestion. Never execute directly from raw
+SonarQube MCP output, quality gate summaries, chat summaries, or remembered
+Sonar findings.

package/skills/massa-ai/references/spec-driven/artifact-store.md

@@ -1,6 +1,6 @@
 # Spec-Driven Artifact Store
 
-Use this reference before any spec-driven workflow reads or writes feature registry, progress, handoff, phase artifacts, validation reports, or lessons. `.specs/` files are the canonical state layer for spec-driven logical artifacts.
+Use before any spec-driven workflow reads or writes feature registry, progress, handoff, phase artifacts, validation reports, or lessons. `.specs/` files are the canonical state layer for spec-driven logical artifacts.
 
 ## Source Of Truth
 

package/skills/massa-ai/references/spec-driven/brownfield-mapping.md

@@ -0,0 +1,16 @@
+# Brownfield Onboarding — 7-Doc Codebase Mapping
+
+Use from `workflows/spec-driven.md` when the target codebase
+has not yet been mapped (brownfield, new repo, or cold project). The map is
+the shared factual ground for requirements, design, and task derivation;
+each doc feeds a downstream phase.
+
+| Doc | Derives | Feeds |
+| --- | --- | --- |
+| `STACK.md` | languages, runtimes, frameworks, key libraries | Design constraints, verification commands |
+| `ARCHITECTURE.md` | layers, modules, boundaries, data flow | Design, risk surface |
+| `CONVENTIONS.md` | naming, file layout, commit/test conventions | Tasks, Execute |
+| `STRUCTURE.md` | directory map, where new code goes | Tasks, file placement |
+| `TESTING.md` | test runner, how to run gates, coverage tooling | Gate Check Commands, verification recipe |
+| `INTEGRATIONS.md` | external services, APIs, contracts, auth | Discuss, risk escalation |
+| `CONCERNS.md` | known risks, tech debt, migration landmines, security/privacy hotspots | Risk-domain escalation, validation focus |

package/skills/massa-ai/references/spec-driven/code-analysis.md

@@ -1,6 +1,6 @@
 # Spec-Driven Code Analysis
 
-Use this reference when Specify, Design, Tasks, Execute, or Validate needs source inspection or structural code search.
+Use when Specify, Design, Tasks, Execute, or Validate needs source inspection or structural code search.
 
 <!-- validator anchors: current repository source and approved .specs/ artifacts override stale memory -->
 

package/skills/massa-ai/references/spec-driven/coding-principles.md

@@ -1,6 +1,6 @@
 # Spec-Driven Coding Principles
 
-Use this reference before writing or changing implementation, tests, fixtures, validation assets, scripts, or docs during Execute.
+Use before writing or changing implementation, tests, fixtures, validation assets, scripts, or docs during Execute.
 
 Behavioral bias, not checklist. Read before every implementation.
 

package/skills/massa-ai/references/spec-driven/context-limits.md

@@ -1,6 +1,6 @@
 # Spec-Driven Context Limits
 
-Use this reference when planning context loading for a spec-driven feature or when `.specs/features/<slug>/` artifacts grow large enough to reduce implementation quality.
+Use when planning context loading for a spec-driven feature or when `.specs/features/<slug>/` artifacts grow large enough to reduce implementation quality.
 
 ## Targets
 

package/skills/massa-ai/references/spec-driven/design.md

@@ -1,6 +1,6 @@
 # Design
 
-Use this reference when the spec-driven flow includes a Design phase. The output is `.specs/features/<slug>/design.md`. **Goal**: define HOW to build it — architecture, components, what to reuse.
+Use when the spec-driven flow includes a Design phase. The output is `.specs/features/<slug>/design.md`. **Goal**: define HOW to build it — architecture, components, what to reuse.
 
 **Skip this phase when:** The change is straightforward — no architectural decisions, no new patterns, no component interactions to plan. For simple features, design happens inline during Execute.
 
@@ -85,6 +85,22 @@ If the feature involves data, define models before implementation.
 
 ---
 
+## Deterministic Validation
+
+Before presenting `design.md` for confirmation, run:
+
+```bash
+bun skills/massa-ai/scripts/validate_design.ts <path-or-feature-or-root> [--root .]
+```
+
+It checks the three structurally-required sections (`## Design Summary`,
+`## Risks & Concerns`, `## Tech Decisions`, heading-prefix match) and that
+every `Risks & Concerns` table row has a non-empty, non-placeholder
+Mitigation cell — a `> None found` marker with zero rows is a valid empty
+risk register, not an unfilled one. A non-zero exit blocks confirmation. If
+no code-execution tool is available, run the same checks by reading the
+artifact (graceful degradation preserved).
+
 ## Required Sections
 
 `design.md` must include:
@@ -100,6 +116,11 @@ If the feature involves data, define models before implementation.
 - Large/Complex approach tradeoffs: 2-3 viable approaches, same scope, recommendation first, user-confirmed chosen approach.
 - Verification design, including how tests or checks prove each high-risk requirement.
 - Risks, concerns, and mitigations.
+- Tech decisions (non-obvious ones only), with rationale.
+
+`## Design Summary`, `## Risks & Concerns`, and `## Tech Decisions` are the
+three headings the deterministic validator above requires structurally;
+the rest of this list is enforced by review, not by the script.
 
 ## Decision Supersession
 

package/skills/massa-ai/references/spec-driven/discuss.md

@@ -1,6 +1,6 @@
 # Spec-Driven Discuss Gray Areas
 
-Use this reference inside Specify when gray areas or implicit requirements affect behavior, scope, data, security/privacy, compatibility, or acceptance criteria. It captures HOW the user envisions the feature when the spec has ambiguous areas — it is NOT a separate phase; it triggers within Specify when the agent detects gray areas that need user input.
+Use inside Specify when gray areas or implicit requirements affect behavior, scope, data, security/privacy, compatibility, or acceptance criteria. It captures HOW the user envisions the feature when the spec has ambiguous areas — it is NOT a separate phase; it triggers within Specify when the agent detects gray areas that need user input.
 
 **Goal:** Capture HOW the user envisions the feature when the spec has ambiguous areas. Specifications capture WHAT to build. Design captures the architecture. But neither captures the user's vision for ambiguous areas — layout preferences, interaction patterns, error handling style, content tone. Without this, the agent guesses. With this, the agent builds what the user actually imagined.
 

package/skills/massa-ai/references/spec-driven/execute.md

@@ -1,6 +1,6 @@
 # Spec-Driven Execute
 
-Use this reference for the required Execute phase. Implement ONE task at a time: surgical changes, verify, commit, repeat. Validation is the mandatory final Execute gate, not a separate phase.
+Use for the required Execute phase. Implement ONE task at a time: surgical changes, verify, commit, repeat. Validation is the mandatory final Execute gate, not a separate phase.
 
 <!-- validator anchors: evidence-or-zero mapping -->
 
@@ -474,6 +474,8 @@ Then run `references/spec-driven/validate.md` as the final Execute gate. The ver
 
 ## Pause / End of Session
 
+**Checkpoints (long-running task sequences):** create a checkpoint via `create_checkpoint` at task boundaries with `taskId`, `description`, `progressPercent`, `currentStep`, `nextAction`, `fileChanges`, and `checkpointType: "manual"` so progress is resumable after interruption. If resuming after interruption, call `list_checkpoints` with the `taskId` and `restore_checkpoint` to recover task state before continuing. If `create_checkpoint` is unavailable (e.g. `task_checkpoints` table missing), continue with `.specs/` artifact state as the fallback.
+
 When work is interrupted, paused, or a session ends before the feature is complete:
 
 1. Update `.specs/project/STATE.md` — append any new decisions to the `## Decisions` section (append-only; decisions are normally written during Design, but runtime decisions discovered during Execute may be appended).

package/skills/massa-ai/references/spec-driven/memory.md

@@ -1,6 +1,6 @@
 # Spec-Driven Memory And State
 
-Use this reference when recording decisions, progress, blockers, handoff, or completion evidence for a spec-driven feature.
+Use when recording decisions, progress, blockers, handoff, or completion evidence for a spec-driven feature.
 
 This memory layer is split across two artifacts with distinct lifecycles. Each has its own write triggers; writes are always section-scoped — never whole-file overwrites.
 

package/skills/massa-ai/references/spec-driven/specify.md

@@ -1,8 +1,8 @@
 # Spec-Driven Specify
 
-Use this reference for the required Specify phase. **Goal**: Capture WHAT to build with testable, traceable requirements. The output is `.specs/features/<slug>/spec.md`.
+Use for the required Specify phase. **Goal**: Capture WHAT to build with testable, traceable requirements. The output is `.specs/features/<slug>/spec.md`.
 
-If the feature has ambiguous gray areas (multiple valid approaches for user-facing behavior), the agent will automatically trigger the [discuss gray areas](discuss.md) process within this phase. For clear, well-defined features, it goes straight to the next phase.
+If the feature has ambiguous gray areas (multiple valid approaches for user-facing behavior), the agent automatically triggers the [discuss gray areas](discuss.md) process within this phase. Clear, well-defined features go straight to the next phase.
 
 ## Inputs
 
@@ -67,7 +67,7 @@ The table is canonical; the prose is the applied sweep. **Large/Complex** work m
 
 **Load confirmed lessons first:** Before clarifying, load the project's confirmed lessons so past verification failures shape this spec instead of repeating. Run `bun skills/massa-ai/scripts/lessons.ts --root . list --status confirmed` (optionally `--scope [area]` or `--query [term]` for the area this feature touches) and apply what comes back as guidance. Load only `confirmed` — never `candidate` or `quarantined`. If no store exists yet or no code tool is available, skip silently. See [lessons.md](../lessons.md).
 
-**Lightweight context scan first (Knowledge Verification Chain Step 1):** Before asking questions, briefly scan existing code, patterns, and neighboring features relevant to this feature. Prefer massa-ai tooling first (`list_projects`, `search`, `project_map`, `optimized_context`) before `ast-grep`/`rg`/`grep`, honoring freshness and source-precedence (current source overrides stale index/memory). Use what you find to ground your clarifying questions in reality — not to constrain the spec to current implementation. Keep it lightweight (stay within the <40k token budget; reuse the chain, no new machinery). The spec captures WHAT is needed, not only what exists.
+**Lightweight context scan first (Knowledge Verification Chain Step 1):** Before asking questions, briefly scan existing code, patterns, and neighboring features relevant to this feature. Prefer massa-ai tooling first (`list_projects`, `search`, `project_map`, `optimized_context`) before `ast-grep`/`rg`/`grep`, honoring freshness and source-precedence (current source overrides stale index/memory). Use what you find to ground clarifying questions in reality — not to constrain the spec to current implementation. Keep it lightweight (stay within the <40k token budget; reuse the chain, no new machinery). The spec captures WHAT is needed, not only what exists.
 
 You are a thinking partner, not an interviewer. Start open — let the user dump their mental model. Follow the energy: whatever they emphasize, dig into that.
 

package/skills/massa-ai/references/spec-driven/sub-agents.md

@@ -1,6 +1,6 @@
 # Sub-Agent Delegation
 
-Use this reference during Execute when formal task planning has more than 3 tasks, when the user explicitly asks for delegation, or when final validation needs an independent verifier. Full mechanics for phase-batch workers and the Verifier sub-agent used during Execute.
+Use during Execute when formal task planning has more than 3 tasks, when the user explicitly asks for delegation, or when final validation needs an independent verifier. Full mechanics for phase-batch workers and the Verifier sub-agent used during Execute.
 
 ## Phase-Batch Workers
 

package/skills/massa-ai/references/spec-driven/tasks.md

@@ -1,6 +1,6 @@
 # Tasks
 
-Use this reference only when the TLC v3 flow includes Tasks. The output is the `.specs/features/<slug>/tasks.md`.
+Use only when the TLC v3 flow includes Tasks. The output is the `.specs/features/<slug>/tasks.md`.
 
 **Goal**: Break into GRANULAR, ATOMIC tasks. Clear dependencies. Right tools. Sequential phase execution plan.
 

package/skills/massa-ai/references/spec-driven/validate.md

@@ -1,6 +1,6 @@
 # Spec-Driven Validate
 
-Use this reference for the mandatory final Execute validation gate. This is not a separate phase — verification is part of every task's completion within Execute and runs automatically after the final task or inline step is complete.
+Use for the mandatory final Execute validation gate. This is not a separate phase — verification is part of every task's completion within Execute and runs automatically after the final task or inline step is complete.
 
 <!-- validator anchors: reject shallow assertions | payload/conjunction rule | per-task test adequacy review summary | fix-loop iteration count | 3 verification iterations -->
 

package/skills/massa-ai/references/subagent-design.md

@@ -1,8 +1,8 @@
 # Subagent Design
 
-Use this reference only when designing or revising a reusable subagent role, adding a new role to `references/agent-orchestration.md`, or turning repeated delegated work into a stable role charter.
+Use only when designing or revising a reusable subagent role, adding a new role to `references/agent-orchestration.md`, or turning repeated delegated work into a stable role charter.
 
-Do not load this reference for ordinary one-off delegation. For runtime delegation, use `references/agent-orchestration.md`.
+Do not load for ordinary one-off delegation. For runtime delegation, use `references/agent-orchestration.md`.
 
 ## Principle
 
@@ -30,7 +30,7 @@ Is the work recurring, specialized, context-heavy, independently verifiable, and
   -> Design a reusable subagent role with this reference.
 ```
 
-Prefer a skill/reference when the value is procedure or domain knowledge. Prefer a subagent when the value is isolated context, parallel work, or independent verification.
+Prefer a skill/reference for procedure or domain knowledge. Prefer a subagent for isolated context, parallel work, or independent verification.
 
 Reusable role threshold:
 
@@ -94,7 +94,7 @@ Memory boundary:
 **The packet field list lives in one place: `references/agent-orchestration.md`,
 §Capability Packet.** Do not restate it here — a second copy is what let the field
 sets drift into three diverging shapes before the canonical section existed. When a
-workflow dispatches a reusable role, send that canonical packet rather than a loose
+workflow dispatches a reusable role, send that canonical packet, not a loose
 instruction.
 
 The one field this reference still names on its own is `persona`, because a