@massa-ai/codex-plugin 1.26.0 → 1.29.0

package/skills/massa-ai/references/mobile-figma-matcher/android-compose.md

@@ -1,6 +1,6 @@
 # Android Jetpack Compose Figma Contract
 
-Load this reference only for Target Surface Packet rows classified as Android Jetpack Compose.
+Load only for Target Surface Packet rows classified as Android Jetpack Compose.
 
 - Resolve composables, modifiers, layout primitives, Material/theme tokens, typography, shapes, painters/assets, state holders, previews/providers, navigation entry, semantics, and test tags affecting the surface.
 - Distinguish Android-only Compose from Compose Multiplatform using module and source-set evidence.

package/skills/massa-ai/references/mobile-figma-matcher/android-views.md

@@ -1,6 +1,6 @@
 # Android Views Figma Contract
 
-Load this reference only for Target Surface Packet rows classified as Android Views XML.
+Load only for Target Surface Packet rows classified as Android Views XML.
 
 - Resolve `res/layout`, qualifiers, includes/merges, styles/themes, dimensions, colors/selectors, text appearances, drawables, fonts, strings, binding/adapters, and Material components affecting the surface.
 - Follow aliases to final values. Record the symbolic resource chain and resolved value.

package/skills/massa-ai/references/mobile-figma-matcher/core.md

@@ -1,6 +1,6 @@
 # Mobile Figma Core
 
-Use this shared reference after `repository-detection.md` identifies one or more target surfaces. It defines Figma evidence, requirements boundaries, asset handling, mapping and comparison semantics, runtime evidence, and parity-claim limits. Load only the platform references named by the Target Surface Packet.
+Use after `repository-detection.md` identifies one or more target surfaces. Defines Figma evidence, requirements boundaries, asset handling, mapping and comparison semantics, runtime evidence, and parity-claim limits. Load only the platform references named by the Target Surface Packet.
 
 ## Boundaries
 

package/skills/massa-ai/references/mobile-figma-matcher/ios-swiftui.md

@@ -1,6 +1,6 @@
 # iOS SwiftUI Figma Contract
 
-Load this reference only for Target Surface Packet rows classified as iOS SwiftUI.
+Load only for Target Surface Packet rows classified as iOS SwiftUI.
 
 - Resolve `View` composition, modifiers, layout containers, environment values, state selection, navigation entry, styles, asset catalogs, symbols, fonts, previews, accessibility modifiers, and UIKit hosting/interoperability affecting the surface.
 - Compare Figma coordinates with SwiftUI points, then account for display scale only for rendered-pixel evidence.

package/skills/massa-ai/references/mobile-figma-matcher/ios-uikit.md

@@ -1,6 +1,6 @@
 # iOS UIKit Figma Contract
 
-Load this reference only for Target Surface Packet rows classified as iOS UIKit.
+Load only for Target Surface Packet rows classified as iOS UIKit.
 
 - Resolve storyboards, XIBs, programmatic views, view controllers, reusable views/cells, Auto Layout constraints, appearance APIs, trait-dependent resources, asset catalogs, fonts, strings, and state configuration.
 - Compare Figma coordinates with UIKit points, then account for device display scale only when validating rendered pixels.

package/skills/massa-ai/references/mobile-figma-matcher/kmp-compose-multiplatform.md

@@ -1,6 +1,6 @@
 # KMP Compose Multiplatform Figma Contract
 
-Load this reference only for shared Compose Multiplatform Target Surface Packet rows.
+Load only for shared Compose Multiplatform Target Surface Packet rows.
 
 - Resolve common composables, shared state, theme/design tokens, Compose resources, adaptive layout, accessibility semantics, platform adapters, and `expect`/`actual` declarations affecting presentation.
 - Keep business/domain behavior in established shared boundaries. Do not move platform-only UI behavior into common code merely to reduce duplication.

package/skills/massa-ai/references/mobile-figma-matcher/repository-detection.md

@@ -1,6 +1,6 @@
 # Mobile Figma Repository Detection
 
-Use this reference before loading any stack-specific matcher reference. Classify the concrete target module and files, not the repository root or repository name.
+Use before loading any stack-specific matcher reference. Classify the concrete target module and files, not the repository root or repository name.
 
 Monorepositories may contain several valid mobile stacks; classify only modules connected to the requested target.
 

package/skills/massa-ai/references/naming-standards.md

@@ -1,6 +1,6 @@
 # Naming Standards
 
-Use this reference when a workflow writes code, drafts implementation contracts, audits code quality, or executes findings that introduce, rename, or preserve identifiers.
+Use when a workflow writes code, drafts implementation contracts, audits code quality, or executes findings that introduce, rename, or preserve identifiers.
 
 ## Goal
 

package/skills/massa-ai/references/pr-task-fix.md

@@ -1,12 +1,12 @@
 # PR Task Fix
 
-Load this reference from `workflows/feature.md` and `workflows/refactor.md` before non-trivial implementation or refactor execution that can be decomposed into reviewable task groups.
+Load from `workflows/feature.md` and `workflows/refactor.md` before non-trivial implementation or refactor execution that can be decomposed into reviewable task groups.
 
 ## ADR/TDD Input Gate
 
 Before decomposition, inspect the first user prompt, current prompt context, explicitly attached or readable local files, and any already supplied Atlassian MCP source pointers.
 
-If there is no ADR or TDD plain text, no attached/readable ADR or TDD file, and no already supplied Atlassian ADR/TDD source, ask whether the user wants to provide an ADR or TDD through Atlassian MCP. Do not ask again when the user has already supplied, declined, or made Atlassian unavailable for this run.
+If there is no ADR or TDD plain text, no attached/readable ADR or TDD file, and no already-supplied Atlassian ADR/TDD source, ask whether the user wants to provide an ADR or TDD through Atlassian MCP. Do not ask again once the user has already supplied, declined, or made Atlassian unavailable for this run.
 
 Use ADR/TDD input as implementation context, not as permission to bypass the active workflow's scope, source verification, or verification recipe. If the ADR/TDD conflicts with current source or project instructions, surface the conflict and resolve it before implementation.
 

package/skills/massa-ai/references/project-context.md

@@ -1,6 +1,6 @@
 # Project Context Intake
 
-Use this reference at the start of every workflow, before the first substantive
+Use at the start of every workflow, before the first substantive
 read, edit, plan, or answer. It defines the minimum project-context sweep that
 makes agent behavior match this repository's actual conventions instead of
 generic defaults.
@@ -41,7 +41,7 @@ When two sources conflict, the higher tier wins:
 6. Current repository source code.
 7. Recalled memory — context only, never canonical.
 
-A conflict between a doc and current source is a finding: report it rather than
+A conflict between a doc and current source is a finding — report it rather than
 silently picking a side.
 
 ## Dedupe Guard

package/skills/massa-ai/references/repo-rules-discovery.md

@@ -1,7 +1,7 @@
 # Repo Rules Discovery
 
-Use this reference from `workflows/spec-driven.md` before the first repository
-mutation. It defines how to discover, load, and enforce the target repository's
+Use from `workflows/spec-driven.md` before the first repository
+mutation. Defines how to discover, load, and enforce the target repository's
 own AI-harness rules and implementation conventions, so spec-driven
 implementation conforms to the repo it runs in rather than only to the
 skill's defaults.
@@ -12,8 +12,8 @@ the target repo**: it loads what is present and never invents what is absent.
 ## Principle
 
 A repository's rules live in its own harness files and conventions. spec-driven
-must read them before implementing and enforce conformance, because a change
-that follows the skill's defaults but violates the repo's module layout, test
+must read them before implementing and enforce conformance — a change that
+follows the skill's defaults but violates the repo's module layout, test
 placement, or lint rules is not deliverable. Silence here reads as "the repo
 has no rules", which is almost never true — it means they were not looked up.
 

package/skills/massa-ai/references/rfc/discovery-and-sizing.md

@@ -1,6 +1,6 @@
 # RFC Discovery And Classification
 
-Load this reference before source investigation, RFC classification, impact selection, or clarification questions.
+Load before source investigation, RFC classification, impact selection, or clarification questions.
 
 ## Workflow Fit
 

package/skills/massa-ai/references/rfc/document-contract.md

@@ -1,6 +1,6 @@
 # RFC Document Contract
 
-Load this reference when drafting or revising an RFC. Preserve the full decision structure while tailoring detail to the RFC type and impact.
+Load when drafting or revising an RFC. Preserve the full decision structure while tailoring detail to the RFC type and impact.
 
 ## Section Contract
 

package/skills/massa-ai/references/rfc/quality-and-lifecycle.md

@@ -1,6 +1,6 @@
 # RFC Quality And Lifecycle
 
-Load this reference before challenging, finalizing, saving, updating, or closing an RFC.
+Load before challenging, finalizing, saving, updating, or closing an RFC.
 
 ## Quality Gate
 

package/skills/massa-ai/references/root-cause-scripts.md

@@ -1,6 +1,6 @@
 # Root-Cause Proof Scripts
 
-Use this reference the moment an implementation or fix stops converging. It is a
+Use the moment an implementation or fix stops converging. It is a
 circuit breaker, not a diagnosis method: it fires mid-implementation in any
 workflow — `feature`, `debug`, `refactor`, `spec-driven`, any `*-fix` — including
 the ones that never opened a reproduction loop.
@@ -11,7 +11,7 @@ This file is where any implementation *stops guessing*.
 ## Principle
 
 An agent that has failed twice on the same symptom does not have a code-reading
-problem. It has a data problem. Reading the same source a third time produces a
+problem — it has a data problem. Reading the same source a third time produces a
 third theory with the same evidence base as the first two. The only way out is
 to make the program tell you what it is actually doing.
 

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

@@ -0,0 +1,256 @@
+# Description & Instruction Examples
+
+Reference for writing effective skill descriptions and instructions.
+Read this during the Architecture phase (for descriptions) and Craft phase
+(for instructions).
+
+---
+
+## Good Descriptions
+
+Each example follows the pattern: [What] + [When/Triggers] + [Not-when].
+
+### Document & Asset Creation
+
+```yaml
+description: Analyzes Figma design files and generates developer handoff documentation.
+  Use when user uploads .fig files, asks for "design specs", "component
+  documentation", or "design-to-code handoff". Do NOT use for general
+  design discussions or UI feedback.
+```
+
+```yaml
+description: Creates distinctive, production-grade frontend interfaces with high design
+  quality. Use this skill when the user asks to build web components, pages,
+  artifacts, posters, or applications (examples include websites, landing
+  pages, dashboards, React components, HTML/CSS layouts, or when
+  styling/beautifying any web UI). Generates creative, polished code and UI
+  design that avoids generic AI aesthetics.
+```
+
+### Workflow Automation
+
+```yaml
+description: Manages Linear project workflows including sprint planning, task creation,
+  and status tracking. Use when user mentions "sprint", "Linear tasks",
+  "project planning", or asks to "create tickets". Do NOT use for general
+  project management advice without Linear context.
+```
+
+```yaml
+description: End-to-end customer onboarding workflow for PayFlow. Handles account
+  creation, payment setup, and subscription management. Use when user says
+  "onboard new customer", "set up subscription", or "create PayFlow account".
+```
+
+### MCP Enhancement
+
+```yaml
+description: Automatically analyzes and fixes detected bugs in GitHub Pull Requests
+  using Sentry's error monitoring data via their MCP server. Use when user
+  mentions "Sentry errors", "fix bugs from monitoring", "PR review with
+  error data", or asks to analyze production errors in code.
+```
+
+---
+
+## Bad Descriptions (and Why)
+
+```yaml
+# ❌ Too vague — no trigger phrases, no specifics
+description: Helps with projects.
+# Why it fails: the agent can't determine WHEN to load this.
+```
+
+```yaml
+# ❌ Missing triggers — describes capability but not activation
+description: Creates sophisticated multi-page documentation systems.
+# Why it fails: What would a user SAY to trigger this? "Create docs"?
+# "Write documentation"? Include the actual phrases.
+```
+
+```yaml
+# ❌ Too technical, no user perspective
+description: Implements the Project entity model with hierarchical relationships.
+# Why it fails: Users don't think in entity models. They think in tasks.
+```
+
+```yaml
+# ❌ Too broad — will overtrigger
+description: Processes documents.
+# Why it fails: Loads for ANY document task. Add file types and specifics.
+```
+
+```yaml
+# ❌ Overlap without boundaries
+description: Analyzes data and creates visualizations.
+# Why it fails: Conflicts with built-in capabilities and other skills.
+# Add specifics about WHAT data and WHAT kind of visualizations.
+```
+
+---
+
+## Fixing Overtriggering with Negative Triggers
+
+```yaml
+# Before: triggers on all data tasks
+description: Advanced data analysis for CSV files.
+
+# After: scoped with negative triggers
+description: Advanced data analysis for CSV files. Use for statistical modeling,
+  regression, clustering. Do NOT use for simple data exploration
+  (use data-viz skill instead) or for reading CSV files without analysis.
+```
+
+---
+
+## Good Instructions
+
+### Specific and Actionable
+
+```markdown
+# ✅ Good — tells the agent exactly what to do
+
+Run `python scripts/[validate].py --input {filename}` to check data format.
+If validation fails, common issues include:
+
+- Missing required fields → add them to the CSV
+- Invalid date formats → use YYYY-MM-DD
+- Encoding errors → convert to UTF-8 first
+```
+
+```markdown
+# ❌ Bad — vague and unactionable
+
+Validate the data before proceeding.
+```
+
+### Error Handling
+
+```markdown
+# ✅ Good — specific error, cause, solution
+
+## Common Issues
+
+### MCP Connection Failed
+
+If you see "Connection refused":
+
+1. Verify MCP server is running: Check Settings > Extensions
+2. Confirm API key is valid
+3. Try reconnecting: Settings > Extensions > [Service] > Reconnect
+```
+
+```markdown
+# ❌ Bad — no specifics
+
+If something goes wrong, try again.
+```
+
+### Resource References
+
+```markdown
+# ✅ Good — says WHEN and WHY to read the file
+
+Before writing queries, consult `references/[api-patterns].md` for:
+
+- Rate limiting guidance (if making >10 calls)
+- Pagination patterns (if results may exceed 100 items)
+- Error codes and handling (if calls may fail)
+```
+
+```markdown
+# ❌ Bad — no guidance on when to read
+
+See references/ for more information.
+```
+
+### Critical Instructions
+
+```markdown
+# ✅ Good — prominent, specific, verifiable
+
+CRITICAL: Before calling create_project, verify:
+
+- Project name is non-empty
+- At least one team member assigned
+- Start date is not in the past
+  If any check fails, tell the user what's missing before proceeding.
+```
+
+```markdown
+# ❌ Bad — buried, vague, not verifiable
+
+Make sure to validate things properly.
+```
+
+### Examples in Skills
+
+```markdown
+# ✅ Good — realistic user input with concrete output
+
+## Examples
+
+### Example 1: New sprint setup
+
+User says: "Help me plan the Q4 sprint for the mobile team"
+Actions:
+
+1. Fetch current backlog from Linear (MCP)
+2. Check team capacity (3 engineers, 2-week sprint)
+3. Prioritize by impact score
+4. Create 12 tasks with estimates
+   Result: Sprint board populated with 12 prioritized tasks, each with
+   story points and assignees. Summary posted to #mobile-team Slack.
+```
+
+```markdown
+# ❌ Bad — generic, no concrete details
+
+### Example 1: Setup
+
+User says: "Set up a project"
+Result: Project gets created.
+```
+
+---
+
+## Anti-Patterns Checklist
+
+Before finalizing any skill, verify NONE of these are present:
+
+### Structural Anti-Patterns
+
+- [ ] File named SKILL.MD, skill.md, or any variant (must be exactly SKILL.md)
+- [ ] Folder has spaces or capitals (must be kebab-case)
+- [ ] README.md exists inside the skill folder
+- [ ] XML angle brackets (< >) in YAML frontmatter
+- [ ] "claude" or "anthropic" in the skill name
+- [ ] Missing --- delimiters around frontmatter
+- [ ] SKILL.md exceeds 500 lines without progressive disclosure
+
+### Description Anti-Patterns
+
+- [ ] No trigger phrases included
+- [ ] Too vague (could match anything)
+- [ ] Too technical (user perspective missing)
+- [ ] No negative triggers when overlap risk exists
+- [ ] Exceeds 1024 characters
+
+### Instruction Anti-Patterns
+
+- [ ] Vague directions without specific actions
+- [ ] Critical instructions buried in middle of document
+- [ ] No examples of realistic usage
+- [ ] No error handling guidance
+- [ ] References to external files without load conditions
+- [ ] Wall-of-text instructions without structure
+- [ ] Assumes skill is the only one loaded
+- [ ] Uses prose where a script would be deterministic
+
+### Quality Anti-Patterns
+
+- [ ] No validation step in workflow
+- [ ] No stopping conditions for iterative processes
+- [ ] Missing rollback/failure handling
+- [ ] Over-reliance on "be careful" instead of specific checks