@massa-ai/codex-plugin 1.26.0 → 1.29.0

package/skills/massa-ai/workflows/skill-architect.md

@@ -0,0 +1,393 @@
+---
+name: skill-architect
+description: 'Expert guide for designing and building high-quality skills from scratch through structured conversation. Use when someone wants to create a new skill, build a skill, design a skill, or asks for help making Agents do something consistently. Also use when someone says "turn this into a skill", "I want to automate this workflow", "how do I teach my Agent to do X", or mentions creating SKILL.md files. Covers standalone skills and MCP-enhanced workflows. Do NOT use for specialized runtime subagent definitions or technical design documents; use the tdd workflow.'
+license: CC-BY-4.0
+metadata:
+  version: "1.0.0"
+---
+
+Attribution: adapted from the `skill-architect` skill by Felipe Rodrigues
+(github.com/felipfr), source Useful-Agent-Skills, licensed CC-BY-4.0.
+
+# Skill Architect
+
+You are a senior skill architect. Your job is to guide users through building the best possible skill for their needs — not by dumping a template, but by deeply understanding their problem first, then crafting a precise solution. Think of yourself as a consultant: you ask the right questions, challenge assumptions, suggest approaches the user hasn't considered, and only write the skill once you have a clear picture.
+
+Load `references/project-context.md` (intake sweep) before the first substantive read.
+
+## Core Philosophy
+
+1. **Understand before building.** Never generate a SKILL.md until you've completed Discovery and Architecture phases. A bad skill is worse than no skill — it triggers incorrectly, gives inconsistent results, and erodes trust.
+
+2. **Progressive disclosure is everything.** The three-level system (frontmatter → SKILL.md body → linked files) exists for a reason: token economy. A bloated skill degrades performance for every conversation it loads into.
+
+3. **Composability over completeness.** Skills coexist with other skills. Never assume yours is the only one loaded. Be a good neighbor.
+
+4. **Specificity beats verbosity.** One precise instruction outperforms three paragraphs of vague guidance. Code beats prose for deterministic checks.
+
+5. **Skills are for agents, not humans.** No README.md inside the skill folder. No onboarding documentation. Write for an LLM that needs clear, actionable instructions.
+
+---
+
+## Workflow Overview
+
+```
+DISCOVERY → ARCHITECTURE → CRAFT → VALIDATE → DELIVER
+```
+
+Move through phases sequentially. Never skip Discovery. Each phase has
+explicit exit criteria before you advance.
+
+---
+
+## Phase 1: Discovery
+
+**Goal:** Build a mental model of what the user needs, why they need it, and
+what "success" looks like.
+
+### 1.1 — Understand the Problem
+
+Start by asking about the OUTCOME, not the implementation. Key questions
+(ask conversationally, not as a checklist dump):
+
+- **What workflow do you want to make consistent?** Get a concrete example
+  of what they do today, step by step.
+- **What goes wrong without the skill?** Understand the pain: inconsistency,
+  forgotten steps, wasted time re-explaining, wrong outputs.
+- **Who will use this skill?** Just them? Their team? Public distribution?
+  This affects naming, documentation depth, and description specificity.
+- **What tools are involved?** Built-in Agents capabilities (code execution,
+  file creation, artifacts) or external services via MCP?
+
+### 1.2 — Define Use Cases
+
+Nail down 2-3 concrete use cases. For each, capture:
+
+```
+Use Case: [Name]
+Trigger: What the user would say or do
+Steps: The sequence of actions
+Tools: Built-in or MCP tools needed
+Result: What success looks like (specific output)
+```
+
+If the user is vague, give them examples to react to. It's easier to refine
+a concrete proposal than to articulate needs from scratch.
+
+### 1.3 — Identify the Category
+
+Determine which category fits best (consult `references/skill-architect/patterns.md` for
+detailed pattern guidance):
+
+| Category                  | When to use                             | Example                                    |
+| ------------------------- | --------------------------------------- | ------------------------------------------ |
+| Document & Asset Creation | Consistent output generation            | Reports, presentations, code, designs      |
+| Workflow Automation       | Multi-step processes with methodology   | Sprint planning, onboarding, deployments   |
+| MCP Enhancement           | Workflow guidance on top of tool access | Sentry code review, Linear sprint planning |
+
+### 1.4 — Establish Success Criteria
+
+Before moving on, agree on how they'll know the skill works:
+
+- **Trigger accuracy:** What should trigger it? What should NOT?
+- **Output quality:** What does a good result look like concretely?
+- **Efficiency:** How many interactions should it take?
+
+**Exit criteria for Discovery:**
+
+- [ ] 2-3 use cases defined with triggers, steps, and expected results
+- [ ] Category identified
+- [ ] Success criteria agreed upon
+- [ ] Tools/dependencies identified
+
+---
+
+## Phase 2: Architecture
+
+**Goal:** Make structural decisions before writing a single line of the skill.
+
+### 2.1 — Choose the Pattern
+
+Based on Discovery findings, select the primary pattern from
+`references/skill-architect/patterns.md`:
+
+1. **Sequential Workflow** — Steps in a specific order with dependencies
+2. **Multi-MCP Coordination** — Workflows spanning multiple services
+3. **Iterative Refinement** — Output quality improves through cycles
+4. **Context-Aware Selection** — Same goal, different tools based on context
+5. **Domain-Specific Intelligence** — Specialized knowledge beyond tool access
+
+Most skills combine patterns. Identify the primary one and note any secondary.
+
+### 2.2 — Plan the Folder Structure
+
+Decide what goes where:
+
+```
+skill-name/
+├── SKILL.md            # Core instructions (target: under 500 lines)
+├── scripts/            # Only if deterministic checks are needed
+├── references/         # Only if domain docs exceed what fits in SKILL.md
+└── assets/             # Only if templates or static files are used in output
+```
+
+**Decision criteria:**
+
+- Is there logic that MUST be deterministic? → Put it in `scripts/`
+- Is there reference material over ~100 lines? → Put it in `references/`
+- Does the output use templates, fonts, or icons? → Put it in `assets/`
+- Everything else → Keep it in SKILL.md
+
+### 2.3 — Design the Description (Critical)
+
+The description field is the most important piece of the entire skill. It
+controls when the agent loads the skill. Draft it now following this structure:
+
+```
+[What it does] + [When to use it with specific trigger phrases] + [What NOT to use it for]
+```
+
+Consult `references/skill-architect/examples.md` for good and bad description examples.
+
+**Key principles:**
+
+- Include actual phrases users would say
+- Include relevant file types if applicable
+- Add negative triggers if overlap with other skills is likely
+- Lean slightly "pushy" — agents tend to undertrigger. Better to load and
+  not need it than to miss a relevant query.
+
+### 2.4 — Plan Progressive Disclosure
+
+Map content to the three levels:
+
+| Level             | What goes here                           | Token budget    |
+| ----------------- | ---------------------------------------- | --------------- |
+| L1: Frontmatter   | name + description                       | ~100 words max  |
+| L2: SKILL.md body | Core workflow, steps, examples           | Under 500 lines |
+| L3: Linked files  | Deep reference, API docs, large examples | As needed       |
+
+SKILL.md should reference linked files clearly with guidance on WHEN to read
+them, so the agent doesn't load everything upfront.
+
+**Exit criteria for Architecture:**
+
+- [ ] Primary pattern selected (with rationale)
+- [ ] Folder structure planned
+- [ ] Description field drafted
+- [ ] Content mapped to disclosure levels
+
+---
+
+## Phase 3: Craft
+
+**Goal:** Write the skill with precision.
+
+### 3.1 — Write the Frontmatter
+
+```yaml
+---
+name: kebab-case-name # Must match folder name
+description: [What + When + Not-when, all on this single line]
+license: CC-BY-4.0
+metadata:
+  author: [ask the user if unknown]
+  version: 1.0.0
+---
+```
+
+**Hard rules:**
+
+- name: kebab-case only, no spaces, no capitals
+- name: never use "claude" or "anthropic" (reserved)
+- description: under 1024 characters
+- description: no XML angle brackets (< >)
+- description: must be a single inline line — do NOT use YAML multiline operators (`>`, `|`, `>-`). Write `description: Your text here` all on one line.
+- license: always `CC-BY-4.0`
+- Delimiters: exactly `---` on their own lines
+
+### 3.2 — Write the Instructions
+
+Use imperative form. Be specific and actionable. Structure:
+
+```markdown
+# Skill Name
+
+Brief purpose statement (1-2 sentences).
+
+## Instructions
+
+### Step 1: [Action]
+
+Specific instructions with examples.
+Expected output: [what success looks like]
+
+### Step 2: [Action]
+
+...
+
+## Examples
+
+### Example 1: [Common scenario]
+
+User says: "..."
+Actions: [numbered steps]
+Result: [specific output]
+
+## Troubleshooting
+
+### Error: [message]
+
+Cause: [why]
+Solution: [fix]
+```
+
+**Writing principles:**
+
+- Prefer explaining WHY over heavy-handed MUSTs
+- Use code/scripts for deterministic validations instead of prose instructions
+- Include 2-3 realistic examples of user inputs and expected outputs
+- Put critical instructions at the top — not buried in middle sections
+- Keep instructions concise; move detailed reference to separate files
+- If referencing files, state exactly WHEN the agent should read them
+- **Never wrap prose lines at arbitrary column widths** (e.g. 80 chars). Let each sentence or paragraph be a single long line. Some UIs and markdown renderers treat hard line breaks mid-paragraph as visual breaks, corrupting the output. Code blocks are exempt — those can wrap for readability.
+
+### 3.3 — Write Supporting Files
+
+For each file in `references/` or `scripts/`:
+
+- Reference it clearly from SKILL.md
+- State the condition under which the agent should load/run it
+- For reference files over 300 lines, include a table of contents
+
+### 3.4 — Anti-Patterns to Avoid
+
+Consult `references/skill-architect/examples.md` for the full anti-pattern list. The critical ones:
+
+- ❌ Vague instructions: "validate things properly"
+- ❌ Instructions too verbose (wall of text the agent will skim)
+- ❌ No examples (agents need concrete input/output pairs)
+- ❌ README.md inside the skill folder
+- ❌ SKILL.MD or skill.md (must be exactly SKILL.md)
+- ❌ Spaces or capitals in folder name
+- ❌ XML angle brackets in frontmatter
+- ❌ Assuming the skill is the only one loaded
+
+**Exit criteria for Craft:**
+
+- [ ] Frontmatter passes all hard rules
+- [ ] Instructions are specific and actionable
+- [ ] Examples included for common scenarios
+- [ ] Error handling documented
+- [ ] Files referenced with clear load conditions
+- [ ] Under 500 lines for SKILL.md body
+
+---
+
+## Phase 4: Validate
+
+**Goal:** Verify the skill before delivery.
+
+### 4.1 — Structural Validation
+
+Run the full checklist from `references/skill-architect/quality-checklist.md` and execute
+`bun scripts/validate_skill.ts <skill-folder>` against the generated skill to check:
+
+- SKILL.md exists with correct casing
+- Frontmatter has required fields with correct format
+- Folder naming is kebab-case
+- No README.md in the skill folder
+- No XML angle brackets in frontmatter
+- Description includes trigger phrases
+
+IF the script cannot run (no code-execution tool available) THEN skip
+`scripts/validate_skill.ts` and run the
+`references/skill-architect/quality-checklist.md` checklist manually instead.
+
+### 4.2 — Trigger Testing
+
+Propose 3-5 test phrases and verify mentally:
+
+**Should trigger:**
+
+- Obvious task requests
+- Paraphrased versions
+- Partial/informal requests
+
+**Should NOT trigger:**
+
+- Unrelated topics
+- Tasks handled by other skills
+- Generic questions
+
+If the description is too broad or too narrow, refine it now.
+
+### 4.3 — Instruction Quality Review
+
+Read the skill as if you're an agent encountering it for the first time:
+
+- Can you follow every step without ambiguity?
+- Are there missing decision points?
+- Would you know when to stop?
+- Are the examples realistic and complete?
+
+### 4.4 — Present Findings
+
+Share the validation results with the user. If issues exist, fix them
+before delivery. If everything passes, move to delivery.
+
+**Exit criteria for Validate:**
+
+- [ ] Structural validation passes
+- [ ] Trigger phrases tested
+- [ ] Instructions are unambiguous
+- [ ] User confirms quality
+
+---
+
+## Phase 5: Deliver
+
+**Goal:** Package and present the completed skill.
+
+### 5.1 — Package
+
+Create the final skill folder structure in the project's skills directory.
+
+### 5.2 — Present
+
+Use `present_files` to share the packaged skill. Include a brief summary:
+
+- What the skill does
+- How to install it in the user's preferred AI agent or IDE
+- Suggested test phrase to try first
+
+### 5.3 — Next Steps
+
+Suggest:
+
+- Test with the suggested phrases
+- If results aren't right, bring the conversation back and iterate
+- For formal evaluation, use the `skill-creator` skill's eval and benchmark modes
+
+---
+
+## Conversation Style
+
+- Ask questions one area at a time — don't dump all Discovery questions at once
+- Give concrete suggestions the user can react to ("Would something like X work?")
+- If the user provides a vague request, propose a specific interpretation and ask
+  if it matches their intent
+- If the conversation already contains a workflow (user says "turn this into a
+  skill"), extract what you can from history FIRST, then fill gaps with questions
+- Match the user's technical level — explain terms if they seem non-technical
+- Be direct about tradeoffs: if a design choice has a downside, say so
+
+## Important Boundaries
+
+- This skill is for CREATING new skills. For improving, evaluating, or
+  benchmarking existing skills, direct users to the `skill-creator` skill.
+- Never generate a SKILL.md without completing Discovery and Architecture.
+  If the user insists on skipping, explain why these phases matter and offer
+  a compressed version rather than skipping entirely.
+- If the user's needs are better served by a simple system prompt or project
+  instruction rather than a full skill, say so. Not everything needs to be a skill.

package/skills/massa-ai/workflows/spec-driven.md

@@ -1,10 +1,18 @@
+---
+name: spec-driven
+description: "Use this workflow for explicit spec-driven requests and broad, ambiguous, migration-heavy, or cross-boundary delivery needing requirements-through-verification control."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### Spec-Driven
 
-Use this workflow for explicit spec-driven requests and broad, ambiguous, migration-heavy, cross-boundary, public-contract, or long-running delivery that needs requirements-through-verification control. Ordinary localized fixes and clear small features stay in `debug`, `feature`, `refactor`, or `general` unless the user explicitly requests this workflow.
+Use for explicit spec-driven requests and broad, ambiguous, migration-heavy, cross-boundary, public-contract, or long-running delivery that needs requirements-through-verification control. Ordinary localized fixes and clear small features stay in `debug`, `feature`, `refactor`, or `general` unless the user explicitly requests this workflow.
 
-Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
-Before the first repository mutation, load `references/implementation-delivery.md` for worktree isolation, atomic commits, PR creation, CI watch, and the merge gate, and `references/code-annotation.md` for doc blocks, rationale comments, and test coverage on every created or updated unit, and `references/repo-rules-discovery.md` to discover and enforce the target repository's own `.claude/`, `.cursor/`, and module/unit-test/testing-area conventions. If two consecutive fix attempts fail on the same symptom, stop editing and load `references/root-cause-scripts.md`.
+Before the first repository mutation, load `references/implementation-delivery.md` (delivery chain: worktree, atomic commits, PR, CI watch, merge gate), `references/code-annotation.md` (doc blocks, rationale, test coverage), and `references/repo-rules-discovery.md` (enforce the target repo's own `.claude/`/`.cursor/` and module/test conventions). After two consecutive failed fixes on one symptom, stop editing and load `references/root-cause-scripts.md`.
 
 ## TLC v3 Flow
 
@@ -40,7 +48,7 @@ Complexity determines depth, not a fixed pipeline. Assess scope first, apply onl
 | Large | >10 tasks OR multi-component feature | Full spec + requirement IDs | Architecture + components | Full breakdown + deps | Implement + verify per task |
 | Complex | Ambiguity or new domain (unfamiliar vocabulary, no prior pattern) | Full spec + discuss gray areas | Research + architecture | Breakdown + phase plan | Implement + interactive UAT |
 
-A "Phase" is an ordered group of Tasks sharing a dependency boundary or a checkpoint commit — it is distinct from a single Task or atomic step. Report sizing in the uniform vocabulary: `1 Phase = X Tasks`; the whole plan is `Y Phases = Z Tasks`. The sub-agent offer fires when a formal `tasks.md` has more than 3 Tasks — packing itself still uses ~7-Task Phase groups; a 4–8-Task feature is offered as a single Phase-group worker.
+A "Phase" is an ordered group of Tasks sharing a dependency boundary or a checkpoint commit — distinct from a single Task or atomic step. Report sizing in the uniform vocabulary: `1 Phase = X Tasks`; the whole plan is `Y Phases = Z Tasks`. The sub-agent offer fires when a formal `tasks.md` has more than 3 Tasks — packing itself still uses ~7-Task Phase groups; a 4–8-Task feature is offered as a single Phase-group worker.
 
 - Specify and Execute are always required.
 - Design is skipped when straightforward (no architectural decisions, no new patterns).
@@ -50,7 +58,7 @@ A "Phase" is an ordered group of Tasks sharing a dependency boundary or a checkp
 
 ## Quick Mode Guardrails
 
-Quick mode is the Small/auto-sized path: a single change touching **max 3 files** with no new dependency and no design decision. It is the fast lane, not a parallel pipeline — it still closes requirements and runs the Execute gate.
+Quick mode is the Small/auto-sized path: a single change touching **max 3 files** with no new dependency and no design decision. Fast lane, not a parallel pipeline — it still closes requirements and runs the Execute gate.
 
 Enter Quick mode only when **all** hold:
 
@@ -74,7 +82,7 @@ Quick artifacts live under `.specs/quick/NNN-slug/` with a `TASK.md` (one-line i
 2. Restore context before planning:
    - `recall` for exact-session continuity, durable decisions, rejected approaches, patterns, blockers, and handoffs.
    - Load `references/spec-driven/artifact-store.md` before reading or writing feature registry, state, handoff, phase artifacts, validation reports, or lessons.
-   - Load `references/synapse-policy.md` when two or more related searches are expected. When the investigation involves multi-search, call `synapse_task_begin` with `id` (the `synapseSessionId`) and `taskContext` before the first search to open a task envelope; call `synapse_prefetch` with `id` and `filePath` after opening a file for deep investigation to warm the buffer; call `synapse_task_end` with `id` when the investigation phase completes. `synapse_task_begin`/`synapse_task_end` require an existing `synapse_session` id.
+   - Load `references/synapse-policy.md` when two or more related searches are expected. For multi-search investigations, run the Synapse task envelope per that reference: `synapse_task_begin` before the first search, `synapse_prefetch` on deep file open, `synapse_task_end` at completion (both `task` calls require an existing `synapse_session` id).
    - Load `references/context-firewall.md` before broad source inspection, generated reports, external research, or verbose tool output.
    - Keep the loaded context budget under the `references/spec-driven/context-limits.md` target; summarize or narrow before loading bulky artifacts.
    - Use `references/spec-driven/code-analysis.md` when source inspection needs structural search or tool fallback.
@@ -85,19 +93,18 @@ Quick artifacts live under `.specs/quick/NNN-slug/` with a `TASK.md` (one-line i
 3. Run `Specify` with `references/spec-driven/specify.md`.
    - Capture stable requirement IDs, testable acceptance criteria, edge cases, and explicit out-of-scope items.
    - Run `references/spec-driven/discuss.md` inside Specify when gray areas, implicit requirements, persistence/state, external calls, auth, payments, concurrency, or state transitions affect behavior.
-   - For Android, iOS, or KMP Compose Multiplatform UI work, load `references/mobile-context.md` and run the optional design-source gate: ask for one or more Figma links, node IDs, a readable desktop selection, supplied screenshots, or explicit `none`; record `Figma Source: none by user choice` when declined. When Figma links or node IDs are supplied, load `references/figma-pre-analysis.md` and run its two-stage sequential retrieval protocol before consuming the design evidence. Screenshots are context-only unless paired with structured Figma evidence. For unsupported targets, record the source as outside mobile Figma scope and do not run mobile Figma.
+   - For Android, iOS, or KMP Compose Multiplatform UI work, run the optional design-source intake gate from `references/mobile-context.md` (Design-Source Intake Gate).
    - Apply the Requirement Closure Gate: every open requirement question is resolved with the user or recorded as an accepted assumption before execution begins.
-4. Decide whether `Design` is required. If yes, run `references/spec-driven/design.md`; if no, record why the skip is valid. When Design is skipped and a design concern appears later, stop and create `design.md` before continuing.
+4. Decide whether `Design` is required. If yes, run `references/spec-driven/design.md`, including its deterministic validation before presenting `design.md` for confirmation; if no, record why the skip is valid. When Design is skipped and a design concern appears later, stop and create `design.md` before continuing.
 5. Decide whether `Tasks` is required. If yes, run `references/spec-driven/tasks.md`; if no, list the inline atomic execution steps before editing. If the inline list reveals more than 5 steps or complex dependencies, stop and create `tasks.md` — the Tasks phase was wrongly skipped (safety valve).
 6. Run `Execute` with `references/spec-driven/execute.md`.
    - Load `references/spec-driven/coding-principles.md` before implementation.
    - Run repo-rules discovery from `references/repo-rules-discovery.md` before the first repository mutation: record the harness sources loaded (or `repo-rules: none present`), and implement so every new or changed file conforms to the target repo's module layout, unit-test location, and testing-area conventions. A repo rule wins over a skill default for placement and gate commands; record any deviation with an explicit reason. Never fabricate rules or create `.claude/`/`.cursor/` directories the repo lacks.
    - Use the Test Coverage Matrix and Gate Check Commands from `tasks.md`, or state their inline equivalents when Tasks was skipped.
    - Ask the MCP and skill question in Tasks or inline Execute when tool choice can change correctness or verification.
-   - If a formal `tasks.md` has more than 3 Tasks, present the sub-agent offer from `references/spec-driven/sub-agents.md` before starting Execute — even when packing yields a single Phase group (a 4–8-Task feature is offered as one Phase-group worker). Offer-then-confirm — never auto-spawn; the user must accept before any sub-agent is dispatched. One worker per Phase group (~7 Tasks, whole Phases): each worker executes all its Tasks in order (implement → gate → atomic commit), then reports a compact summary (Tasks done, commit hashes, test counts, deviations). Workers never spawn further sub-agents.
+   - If a formal `tasks.md` has more than 3 Tasks, present the sub-agent offer from `references/spec-driven/sub-agents.md` before starting Execute — even when packing yields a single Phase group (a 4–8-Task feature is offered as one Phase-group worker).
    - Implement one atomic step or approved task at a time.
-   - For 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.
+   - For long-running task sequences, use the checkpoint mechanism in `references/spec-driven/execute.md` (Pause / End of Session) so progress is resumable after interruption.
    - Use per-task commits when the environment and user permissions allow commits; otherwise record the skipped reason.
    - Keep validation assets protected.
    - Update logical feature artifacts in `.specs/features/<slug>/` and `.specs/project/STATE.md` after meaningful progress.
@@ -117,7 +124,7 @@ Quick artifacts live under `.specs/quick/NNN-slug/` with a `TASK.md` (one-line i
     - The verification-agent re-derives coverage independently using evidence-or-zero and does not inherit the author's mental model.
    - The fix → re-verify loop is capped at 3 iterations before escalating to `Blocked`.
    - Distill lesson signals through `references/lessons.md` when validation produces grounded reusable failures.
-7. Before the delivery chain's Propose stage (PR creation), write and commit `.specs/project/STATE.md`, `.specs/HANDOFF.md`, and `.specs/project/FEATURES.json` on the branch — not merely "after meaningful progress" during Execute, but committed before `gh pr create`. **Deterministic backing (run it, do not eyeball it):** `bun skills/massa-ai/scripts/check_specs_delivered.ts <feature> [--root .]` — a non-zero exit blocks Propose (see `references/implementation-delivery.md` stage 3.5 and GATE-02). If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved). Record `references/spec-driven/memory.md` decisions, blockers, handoff, and completion evidence per that reference's write triggers.
+7. Before the delivery chain's Propose stage (PR creation), write and commit `.specs/project/STATE.md`, `.specs/HANDOFF.md`, and `.specs/project/FEATURES.json` on the branch — not merely "after meaningful progress" during Execute, but committed before `gh pr create`. **Deterministic backing (run it, do not eyeball it):** `bun skills/massa-ai/scripts/check_specs_delivered.ts <feature> [--root .]` — a non-zero exit blocks Propose (see `references/implementation-delivery.md` stage 3.5 and GATE-02). If no code-execution tool is available, run the same checks by reading the artifact (graceful degradation preserved). Record decisions, blockers, handoff, and completion evidence per `references/spec-driven/memory.md`'s write triggers.
 8. When the user splits planning and implementation across clean chats, resume from the canonical `.specs/` artifacts — `.specs/project/STATE.md`, `.specs/project/FEATURES.json`, `.specs/HANDOFF.md`, and the feature's phase files. This workflow owns the spec phase contracts on both sides of the split; there is no separate save/load procedure.
 9. Complete the configured Plan Challenge Gate for non-trivial plans and complete `references/evidence-gate.md` before claiming completion.
 
@@ -166,17 +173,7 @@ Step 5: Flag as uncertain → "I'm not certain about X — here's my reasoning,
 
 ## Brownfield Onboarding — 7-Doc Codebase Mapping
 
-When the spec-driven work targets a codebase the agent has not yet mapped (brownfield, new repo, or cold project), derive a 7-doc codebase map before Specify closes. The map is the shared factual ground for requirements, design, and task derivation; it is not busywork — 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 |
+When the spec-driven work targets a codebase the agent has not yet mapped (brownfield, new repo, or cold project), derive the 7-doc codebase map from `references/spec-driven/brownfield-mapping.md` before Specify closes — not busywork, each doc feeds a downstream phase.
 
 Minimum bar: derive at least **`CONCERNS.md`** (risk surface — drives risk-domain escalation and validation focus) and **`TESTING.md`** (gate derivation — exact commands the Execute gate will run). If time or access is constrained, these two are non-negotiable; the other five are derived as the work needs them. Record the map under `.specs/features/<slug>/` (or the project onboarding dir) and confirm it against current source, not memory or external summaries.
 

package/skills/massa-ai/workflows/tdd.md

@@ -1,8 +1,16 @@
+---
+name: tdd
+description: "Use this workflow to write a Technical Design Document once one product direction is selected and no unresolved API, data, security, or rollout decision blocks implementation."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### TDD (Technical Design Document)
 
-Use this workflow when the readiness checklist is true: one product direction is selected, a named requirements source exists, and no unresolved API, data, security/privacy, migration, rollout, or public compatibility decision blocks implementation design. Route unresolved proposals or competing directions to `workflows/rfc.md`, isolated finalized architecture decisions to `workflows/adr.md`, and broad requirements-to-delivery work to `workflows/spec-driven.md`.
+Use when the readiness checklist is true: one product direction is selected, a named requirements source exists, and no unresolved API, data, security/privacy, migration, rollout, or public compatibility decision blocks implementation design. Route unresolved proposals or competing directions to `workflows/rfc.md`, isolated finalized architecture decisions to `workflows/adr.md`, and broad requirements-to-delivery work to `workflows/spec-driven.md`.
 
-Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
 ## Workflow
 

package/skills/massa-ai/workflows/tests/tests-audit.md

@@ -1,12 +1,20 @@
+---
+name: tests-audit
+description: "Findings-only audit of test coverage, regression protection, assertion quality, fixture reliability, and missing deterministic sensors in a concrete target."
+license: MIT
+metadata:
+  version: "1.1.0"
+---
+
 ### Tests Audit
 
-Use this workflow for findings-only audit of test coverage, regression protection, assertion quality, fixture reliability, and missing deterministic sensors in a concrete target: modified files, explicit files/globs, commit ranges, branch comparisons, modules/packages, symbols/classes/functions, feature/runtime flows, explicitly requested whole-repo scope, or an implementation scope packet supplied by `workflows/implementation/implementation-audit.md`.
+Findings-only audit of test coverage, regression protection, assertion quality, fixture reliability, and missing deterministic sensors, scoped to a concrete target: modified files, explicit files/globs, commit ranges, branch comparisons, modules/packages, symbols/classes/functions, feature/runtime flows, explicitly requested whole-repo scope, or an implementation scope packet supplied by `workflows/implementation/implementation-audit.md`.
 
-Before the first substantive read, load `references/project-context.md` and run the project-context intake sweep for this repository.
+Load `references/project-context.md` (intake sweep) before the first substantive read.
 
-Do not use this workflow to write, run, or fix test findings as the main task; route that to `workflows/tests/tests-fix.md`. Do not use it for generic correctness, security, architecture, code quality, or requirements findings; route those to the dedicated workflows.
+Not to write, run, or fix test findings as the main task — route to `workflows/tests/tests-fix.md`. Not for generic correctness, security, architecture, code quality, or requirements findings — route to the dedicated workflows.
 
-This workflow is findings-only. Do not edit code unless the user separately asks for fixes.
+Findings-only: do not edit code unless the user separately asks for fixes.
 
 1. Resolve/reuse `workflowSessionId`: `test-audit-[entity]`
 2. Load shared references:
@@ -31,32 +39,8 @@ This workflow is findings-only. Do not edit code unless the user separately asks
    - Implementation parent scope: use only when `workflows/implementation/implementation-audit.md` invokes this workflow with a concrete implementation scope packet.
    - If the target focus is missing, vague, or too broad, ask for a concrete target from the supported scope types in `references/audit-scope.md`.
    - Build the shared scope packet from `references/audit-scope.md` and carry it into the report.
-5. For modified files scope:
-   - Include staged and unstaged tracked files from the working tree.
-   - Include untracked non-generated source, test, fixture, schema, config, and docs files only when they can affect runtime, validation, or test behavior.
-   - Exclude deleted files unless their deletion can break test coverage, imports, exports, routing, migrations, config, tests, or packaging.
-   - Exclude generated, dependency, build, log, cache, temporary, and secret paths per repo rules.
-   - Inspect diffs first, then tests and surrounding code needed to understand regression risk.
-6. For commit range scope:
-   - If the user supplied explicit commits or a revision range, use that exact range.
-   - If the user asked for commits made by me, resolve author identity from `git config user.email`; if empty, use `git config user.name`.
-   - For branch-relative commit scopes, resolve the branch base from the upstream merge-base first, then fall back in order to `origin/main`, `origin/master`, `main`, and `master`.
-   - If the user asked for commits made by me, review branch-unique commits authored by the resolved identity.
-   - If no explicit range, required author identity, or branch base can be resolved, ask the user for the missing value before proceeding.
-   - Inspect changed files and diffs from those commits, then tests, fixtures, config, schemas, and prior bug patterns only as needed.
-7. For codebase area scope:
-   - Require a concrete path, module, package, feature area, or glob.
-   - If the target area is missing, ask for it before proceeding.
-   - Follow the shared retrieval order from `references/codebase-investigation.md` to find production entry points, tests, fixtures, mocks, test commands, and coverage-sensitive config.
-8. For explicit files/globs, branch comparison, symbol/class/function, feature/flow, or explicitly requested whole-repo scope:
-   - Resolve the target with `references/audit-scope.md` and record the resolution method, base/head when relevant, resolved files, exclusions, and freshness timestamp.
-   - For symbol/class/function targets, inspect definitions, call paths, behavior contracts, tests, fixtures, mocks, and test commands only as needed.
-   - For feature/flow targets, map changed or targeted behavior to existing tests and deterministic harnesses.
-   - If whole-repo scope is requested, map major test surfaces first and report skipped depth checks rather than implying exhaustive coverage.
-9. For implementation parent scope:
-   - Accept the exact scope packet from `implementation-audit`; do not broaden beyond resolved files, nearby tests, fixtures, config, and callers needed to verify regression protection.
-   - Return compact findings to the parent implementation audit; do not write broad project memories unless explicitly assigned.
-10. Investigation pass. Dispatch `audit-specialist` per `references/agent-orchestration.md` when the scope justifies an isolated read-only subagent:
+5. Resolve the selected branch's mechanics (modified files, commit range, codebase area, explicit-files/branch/symbol/feature/whole-repo, or implementation parent scope) per `references/audit-scope.md` (Lens Audit Scope Resolution Procedure, Tests row of Per-Lens Scope Deltas).
+6. Investigation pass. Dispatch `audit-specialist` per `references/agent-orchestration.md` when the scope justifies an isolated read-only subagent:
 
 > **Dispatch: `massa-ai-audit-specialist`** (role: `audit-specialist`) — charter `skills/agents/audit-specialist/SKILL.md`
 > - trigger: large scope, explicit parallel/subagent request, PR subagent invocation, or independent verification of high-impact finding
@@ -74,17 +58,17 @@ This workflow is findings-only. Do not edit code unless the user separately asks
    - For mobile scopes, check KMP shared and platform-specific `actual` tests, Android/iOS harnesses, native bridge payload coverage, permissions, lifecycle, offline sync, deep links, push/background flows, UI snapshots/screenshots, device-matrix assumptions, and platform parity claims from `references/mobile-context.md`.
    - Check weak assertions, tests that only assert implementation details, fixture drift, nondeterminism, hidden network/time/filesystem dependencies, skipped tests, and weakened snapshots.
    - For each candidate finding, record the concrete claim, source evidence, impacted behavior, likely regression path, provisional severity, and what would disprove it.
-11. False-positive pass:
+7. False-positive pass:
    - Try to disprove every candidate before reporting it.
    - Check existing unit, integration, e2e, contract, snapshot, fixture, and harness coverage; also check framework-generated coverage and accepted exceptions.
    - If a deterministic test command is cheap and in scope, run it as a sensor; if not, report the skipped command and reason.
    - Drop candidates disproven by evidence, downgrade candidates with partial mitigation, and mark low-confidence findings explicitly.
-12. Severity rules (apply the countable threshold first, then the qualitative clause):
+8. Severity rules (apply the countable threshold first, then the qualitative clause):
    - `critical`: missing or broken tests around data loss, auth/privacy, migration, deployment-blocking, irreversible corruption risk, OR >10 affected files; otherwise use the qualitative clause below.
    - `high`: missing or weak tests around a core flow, public contract, persistence behavior, validation, security boundary, or severe regression risk.
    - `medium`: missing edge-flow coverage, flaky or nondeterministic test risk, fixture drift, weak assertions, or missing regression coverage around changed logic (<=10 affected files).
    - `low`: minor coverage gap, low-impact assertion hardening, incomplete evidence, or weakly supported concern.
-13. Final report:
+9. Final report:
    - Findings first, ordered by severity: `critical`, `high`, `medium`, `low`.
    - Each finding must use `TST-<N>` and include the canonical fields from `references/audit-report-io.md`: severity, confidence, file/line, evidence, impacted behavior, regression risk, simplest test direction, deterministic sensor, and verification suggestion.
    - If no test audit findings are found, say that clearly and list scope checked plus skipped checks.
@@ -93,11 +77,11 @@ This workflow is findings-only. Do not edit code unless the user separately asks
    - Include the Verification/Test Fidelity Checklist from `references/audit-report-io.md`; tie every `TST-*` finding or no-finding claim to deterministic sensors, commands/artifacts, results, validation assets, or skipped-check reasons. Model judgment alone cannot satisfy verification/testing all-clear.
    - For direct top-level invocation, use the Plan Mode save rule and canonical report contract from `references/audit-report-io.md` for `audits/tests/<YYYY-MM-DD tests-audit>.md`.
    - For implementation audit child invocation, return compact findings to the parent unless the parent explicitly requests saved audit artifacts.
-14. Persist only durable knowledge:
+10. Persist only durable knowledge:
    - Do not persist one-off findings.
    - Persist repeated test gap patterns, project-specific testing conventions, accepted exceptions, flaky-test patterns, or reusable verification recipes after scoring with the Importance Calibration System.
    - Use required tags: `project:<projectId>`, `session:<workflowSessionId>`, `workflow:tests-audit`, `entity:<entity>`, and one `memory:<tier>` tag.
-15. Complete the Evidence Gate from `references/evidence-gate.md`.
+11. Complete the Evidence Gate from `references/evidence-gate.md`.
 
 ## Examples