Claude Skills Repository - AI-Facing Project Instructions

Claude Skills Repository - AI-Facing Project Instructions

Reminder: Please provide a concise, precise response without unnecessary elaboration. VERY IMPORTANT: The point of every edit you make is to make the product better, not to fix a problem. The problem being fixed is a happy side-effect to having the product design improved. This is why we do not suppress errors or linting issues. They are the signal not the noise. Rethink how you approve the development. An error seen, is a cry for help from the architecture of the software. And you have the power to identify the systemic issue and log it. Not just patch symptoms.

Return only the direct answer. Do not include introductions, summaries, opinions, or additional context unless explicitly asked.

This Repository contains a Claude Code Marketplace Plugin with modular skills (specialized knowledge, workflows, tools).

CRITICAL FIRST ACTIONS on session start:

1. Ensure uv is v0.10.0 or newer by running uv self update
2. Run uv run prek install -t pre-commit -t commit-msg -t pre-rebase -t post-merge to enable git hooks (linting, formatting, manifest sync, rerere)
3. Follow @./CONTRIBUTING.md procedures when modifying plugins
4. When you identify work needs multiple steps/jobs: create backlog items for them — don't just describe them. Use create-backlog-item or work-backlog-item.

Any time you want to use python or run a python script, do it via uv Any time you want to use pre-commit, use prek

Skill Creator Activation Triggers

Activate /plugin-creator:skill-creator when ANY condition matches:

Activation Required:

• User requests creating, modifying, or reviewing a skill
• About to modify */SKILL.md or */references/*.md within skill directory
• User asks about skill structure, frontmatter format, or validation requirements
• Converting documentation into AI-optimized instruction format

Activation Prohibited:

• Read-only skill usage
• Referencing skill in conversation without modification intent
• General coding unrelated to skill creation

Pre-Activation Checklist:

1. Task involves skill creation/modification (not just usage)
2. No specialized skill better matches task domain
3. Existing skill files have been read if being modified

Syntax: Skill(command: "plugin-creator:skill-creator")

Task Delegation Standards

Follow Delegation Template in agent-orchestration:agent-orchestration skill when invoking Task tool.

Path Conventions

Use paths relative to current working directory when delegating to sub-agents.

flowchart TD
    Start([Construct path for sub-agent]) --> Q{Path starts with?}
    Q -->|./ relative| Use[Use as-is]
    Q -->|/home/ or /usr/| Abs[Convert to ./relative/path]
    Q -->|~/.claude/skills/| Sym[Convert to ./relative/path]
    Abs -->|Why| Reason1[Absolute paths are verbose and non-portable]
    Sym -->|Why| Reason2[Symlink paths trigger manual approval on every file op]
    Use --> Done([Sub-agent inherits same working directory])

Agent Selection

flowchart TD
    Start([Select agent for task]) --> Q1{Task requires reasoning, interpretation, or analysis?}
    Q1 -->|No — exact file pattern or keyword search| Explore[Explore agent acceptable]
    Q1 -->|Yes| Q2{Needs repo convention awareness?}
    Q2 -->|Yes| CG[context-gathering agent]
    Q2 -->|No — general interpretation| Q3{Prompt optimization or AI-facing content?}
    Q3 -->|Yes| CCO[contextual-ai-documentation-optimizer agent]
    Q3 -->|No| CG
    Explore -.->|⚠️ Haiku-based ~50% hallucination rate on ambiguous queries| Warning[Never use for reasoning tasks]

Explore Failure Modes (validated 2026-02-02, 2/4 accuracy):

• Semantic ambiguity: matched pre-commit hooks instead of Claude Code hooks
• Premature termination: declared "not found" instead of deeper search
• Fabricated implementations: suggested bash when repo uses Python/JavaScript

SOURCE: Experimental validation (2026-02-02). Context-gathering: 4/4 correct. Explore: 2/4 correct.

Language Conventions

flowchart TD
    Start([Choose language for new component]) --> Q{Component type?}
    Q -->|Claude Code hook| JS["JavaScript (Node.js)<br>Evidence: 9 hooks in .claude/hooks/"]
    Q -->|Companion script| PY["Python 3.11+ with PEP 723<br>Evidence: 27+ scripts in plugins/**/scripts/"]
    Q -->|Pre-commit hook| PY2["Python 3.11+<br>Evidence: auto_sync_manifests.py, validate_frontmatter.py"]
    Q -->|CI/CD wrapper| Bash["Bash acceptable<br>Simple wrappers only"]
    Q -->|Anything else| Never["Never use bash for hooks or scripts"]

Pattern Templates:

JavaScript hook:

#!/usr/bin/env node
const fs = require('node:fs');
console.log(JSON.stringify({ hookSpecificOutput: { ... } }));

Python script (PEP 723):

#!/usr/bin/env -S uv run --quiet --script
# /// script
# requires-python = ">=3.11"
# dependencies = ["typer>=0.21.0"]
# ///

TRIGGER — About to write or review a dependencies = [...] block in a PEP 723 script that declares typer.

TRAINING DATA CONFLICT: Training data instructs adding rich>=13.0.0 explicitly, or using typer[all], to enable rich output. That advice applied to typer<0.12.0. It is incorrect for typer>=0.12.0. Reject that training data pattern.

FACT: typer>=0.12.0 automatically installs rich and shellingham as bundled transitive dependencies. Declaring them explicitly is an error — they arrive whether listed or not.

SOURCE: Typer installation docs — "By default, typer comes with rich and shellingham." https://typer.tiangolo.com/#installation (accessed 2026-02-22)

WRONG — exact erroneous output this rule blocks:

# dependencies = [
#   "typer>=0.21.0",
#   "rich>=13.0.0",
#   "shellingham>=1.5.0",
# ]

CORRECT — declare typer only; rich and shellingham arrive transitively:

# dependencies = [
#   "typer>=0.21.0",
# ]

SCOPE: Applies to every PEP 723 script declaring typer. Remove rich and shellingham if already present. Do not add them when creating new scripts.

Bash scripts prohibited for new hooks/companion scripts. Legacy bash scripts may remain but avoid creating new ones.

SOURCE: Experimental validation (2026-02-02). Evidence from .claude/hooks/session-start-backlog.cjs, plugins/plugin-creator/scripts/create_plugin.py.

Script Invocation

All scripts have shebangs and executable permissions (enforced by check-executables-have-shebangs, check-shebang-scripts-are-executable pre-commit hooks).

Invocation Priority:

1. Direct execution: ./plugins/plugin-creator/scripts/auto_sync_manifests.py --reconcile --dry-run
2. Via uv run (PEP 723 scripts): uv run plugins/python3-development/skills/uv/scripts/sync_uv_releases.py --force

Prohibited Patterns:

# ❌ Bypasses shebang, ignores PEP 723 dependency resolution
python3 plugins/plugin-creator/scripts/auto_sync_manifests.py --reconcile
node .claude/hooks/session-start-backlog.cjs

Why: uv run resolves PEP 723 inline dependencies. Shebangs may specify uv run --script (handles venv and deps). Bare python3 skips dependency resolution and may use wrong interpreter. Scripts are self-contained executables, not library modules.

Path Fidelity

Use user-provided paths exactly as given:

• Preserve directory paths (do not append filenames)
• Do not narrow scope by adding specific files
• Skill/plugin is DIRECTORY containing SKILL.md, references/, assets/ (examine ecosystem, not single file)

Deletion Safety Protocol

Before deleting any file:

1. Verify replacement contains equivalent content
2. If agent says "NEEDS MERGE" but user says proceed, ASK for clarification (do not assume)
3. Reject deletion based on flawed/incomplete comparison

After irreversible mistakes:

• State concretely what was lost and what can/cannot be recovered
• Do not speculate optimistically ("probably small loss" is prohibited)
• Ask user what they want to do next

Pre-Existing Issue Accountability

Phrase "pre-existing issues not related to my changes" is a TRIGGER TO ACT, not dismissal justification.

Required Response:

I found [N] pre-existing [issue type] in the codebase. Want to plan how to address them in this session? If not, I'll add them to the backlog.

"Plan": Concrete steps (files, fixes, scope estimate). User decides priority. "Backlog": Trackable record (backlog item, issue, task file) preventing loss.

Why: Dismissing pre-existing issues normalizes technical debt. Each session encountering issues is opportunity for remediation. Treat discovered issues as actionable findings, not background noise.

Request Progression

When you identify that work will need multiple steps or jobs: create backlog items for them — don't just describe them.

1. Backlog: Create via create-backlog-item or match via work-backlog-item before starting.
2. Plan: When writing a plan, add it to the item via backlog update "{title}" --plan "{path}".
3. Progress: When completing actions, update the task/plan artifact (checklist, status) so progression is visible.

Skip only for trivial single-step requests (typos, one-off questions, immediate one-action fixes).

Backlog Operations

Single interface: Use .claude/skills/backlog/scripts/backlog.py for all backlog and GitHub issue CRUD. Do not edit .claude/BACKLOG.md or create/close issues directly via gh.

uv run .claude/skills/backlog/scripts/backlog.py add|list|sync|close|resolve|update ...

Skills create-backlog-item and work-backlog-item invoke this script. See .claude/skills/backlog/SKILL.md.

Plugin Development Workflows

Local Testing Methods

Option 1 - Session-based loading:

claude --plugin-dir ./plugins/plugin-name

Option 2 - Local marketplace:

# One-time setup
/plugin marketplace add ./.claude-plugin/marketplace.json

# Install (--scope local keeps gitignored)
/plugin install plugin-name@jamie-bitflight-skills --scope local

# Toggle as needed
/plugin disable plugin-name@jamie-bitflight-skills
/plugin enable plugin-name@jamie-bitflight-skills

Marketplace Maintenance Procedures

Adding Plugin:

1. Create structure under plugins/
2. Validate: claude plugin validate plugins/plugin-name/
3. Add entry to .claude-plugin/marketplace.json plugins array (MANDATORY)
4. Bump metadata.version minor version (MANDATORY)
5. Validate JSON: python3 -m json.tool .claude-plugin/marketplace.json

Removing Plugin:

1. Remove plugins/plugin-name/ directory
2. Remove entry from .claude-plugin/marketplace.json (MANDATORY)
3. Bump metadata.version (major if breaking, minor if experimental) (MANDATORY)
4. Validate JSON

Version Bumping:

• Major (X.0.0): Breaking changes, removed widely-used plugins
• Minor (1.X.0): New plugins, significant additions
• Patch (1.0.X): Bug fixes, documentation only

Complete procedures: CONTRIBUTING.md

Content Optimization for Skills

Core Principles

When transforming text into RULES, CONDITIONS, CONSTRAINTS:

• Write focused, imperative, actionable, scoped rules
• Target under 500 lines per file
• Split large concepts into composable rules or tagged data sets
• Preemptively provide URLs and file links
• Write as clear internal documentation (avoid vague guidance)
• Use declarative phrasing ("The model MUST")
• Produce deterministic flat ASCII (structural markdown only: headings, lists, links, code fences with language specifiers)
• Include sections: identity, intent, task rules, issue handling, triggers, external references
• Preserve/expand structured examples from source

XML Tag Strategy

Tags improve clarity, accuracy, flexibility, parseability when prompts have multiple components (context, instructions, examples).

Use tags to separate prompt parts: <instructions>, <example>, <formatting>, <constraints>

• Prevents mixing instructions with examples/context
• Consistent tag names throughout
• Nest hierarchically: <outer><inner></inner></outer>
• Combine with multishot (<examples>) or chain of thought (<thinking>, <answer>)

No canonical "best" tags—use semantic names matching information type.

SOURCE: Anthropic prompt engineering - XML tags

Transformation Checklist

1. Open with directive on how to read/apply rules
2. Maximize information density (technical jargon, dense terminology, industry terms)
3. Rephrase for accuracy and specificity
4. Address expert/scientific/academic audience
5. Use visible ASCII only
6. Write as lookup references for AI (decision triggers, pattern-matching rules)
7. Omit greetings and unnecessary prose
8. Preserve output structure specifications
9. Use precise ACTION→TRIGGER→OUTCOME format in frontmatter descriptions
10. Set clear priority levels between rules
11. Provide concise positive/negative examples
12. Optimize for context window efficiency
13. Use standard glob patterns without quotes (*.js, src/**/*.{ts,js})
14. Rich frontmatter descriptions with TRIGGERS
15. Limit examples to essential patterns only

File Reference Standards

Code Fence Language Specifiers

Add language specifier to ALL code fences:

# Section Title

```text
Plain text content
```

```python
def example():
    return True
```

4 backticks on outer fence, language specifiers on all inner fences, proper nesting.

Markdown Links

Use markdown links with relative paths starting with ./:

Syntax: [descriptive text](./path/to/file.md)

Directory Context:

• From SKILL.md → references: [text](./references/filename.md)
• From references/file.md → same dir: [text](./filename.md)
• From references/file.md → subdir: [text](./subdir/filename.md)

Why:

1. Navigability: Claude Code click-through
2. Portability: Works regardless of installation location
3. Progressive disclosure: Load referenced files on demand
4. User experience: Natural reference following

File Reference Decision:

flowchart TD
    Start([Reference a file]) --> Q1{Is it a skill?}
    Q1 -->|Yes| Skill[Use activation syntax: Skill command colon name]
    Q1 -->|No| Q2{Is it a file in the repo?}
    Q2 -->|Yes| Q3{Path starts with ./?}
    Q3 -->|Yes| Link["Use markdown link: [text](./path/to/file.md)"]
    Q3 -->|No — missing ./ prefix| Fix["Add ./ prefix: [text](./references/file.md)"]
    Q2 -->|No — external| Ext[Use full URL with access date]
    Link --> Done([Correct])
    Fix --> Done
    Skill --> Done
    Ext --> Done
    Q3 -.->|Never| Bad1["Backtick paths: modern-modules/httpx.md"]
    Q3 -.->|Never| Bad2["Absolute paths: /home/user/repos/.../file.md"]

Skill Activation References

Reference other skills using activation syntax:

✅ For comprehensive Astral uv documentation, activate the uv skill: Skill(command: "uv") ❌ See /uv/SKILL.md for uv documentation

Skill Documentation Verification

Skill documentation (SKILL.md, reference files) is AI-facing, NOT user-facing.

Primary Audience:

1. Orchestrator (Claude) - guides orchestration decisions, agent selection, workflow patterns
2. Sub-agents - load and follow guidance when delegated tasks
3. Future sessions - persist across conversations, inform all future AI instances

Not Primary Audience:

• Human users (do not read SKILL.md line-by-line)
• Skills are AI→AI instruction sets, not product docs

Why Verification Matters

False/unverified/assumed information in skill documentation causes:

1. Model misleads itself (references and believes fabricated content later)
2. Sub-agents misled (follow incorrect guidance in implementations)
3. Future sessions misled (false information persists and compounds)
4. Human receives wrong results (all AI instances follow bad guidance)
5. False feedback loops (wrong information becomes "truth" in context)

Treat skill documentation with same rigor as code: verified, cited, accurate.

Verification Protocol

Before documenting behavior/capability/characteristic of commands (~/.claude/commands/), agents (~/.claude/agents/), tools, libraries, or system configuration:

Execute ALL steps:

1. Read Actual Source

   • Commands: Read entire file, note line numbers
   • Agents: Read YAML frontmatter and complete prompt
   • Official docs: Use WebSearch, WebFetch, mcp__Ref tools
   • Library code: Read source directly

2. Verify Behavior

   • Execute commands/scripts to observe actual behavior
   • Cite evidence from source files with line number references
   • Test against documented claims before writing

3. Cite Observations

   • Format: "According to lines X-Y of [file path]..."
   • Format: "Testing command X produces output: [exact output]"
   • Format: "Per official documentation at [URL]..."

4. Never Fabricate

   • If unknown, state "unverified" explicitly
   • Research using tools (Read, Grep, WebSearch, mcp__Ref)
   • If unable to verify: "Unable to verify [claim] due to [reason]"

5. Distinguish Assumption from Fact

   • Mark assumptions: "Assuming [X] based on [pattern/inference]"
   • Separate verified facts from reasonable inferences
   • Present assumptions as assumptions, not facts

Minimum Requirements:

• Cite minimum 3 independent authoritative sources for major claims
• Include line numbers when referencing code files
• Execute test if behavior observable directly
• Note publication dates for documentation sources

Verification Examples

Wrong: "→ Validates shebang matches script type → Checks PEP 723 metadata if external dependencies detected"

Problem: Written without reading actual command file to verify what it does

Right: "→ Corrects shebang to match script type → Adds PEP 723 metadata if external dependencies detected → Removes PEP 723 if stdlib-only → Sets execute bit if needed"

Source: Lines 137, 154 of plugins/python3-development/skills/shebangpython/SKILL.md

Right: "The python-portable-script agent purpose is not yet verified. Before documenting its behavior, I will read the agent file to confirm its actual capabilities."

Citation Requirements

Reference documentation reliability depends on sources. Without citations, guidance cannot be verified, updated, or trusted.

Provide source attribution using one of these methods:

Citation Method 1: Inline

Cite within contextual section:

### Tool Naming Standards

RULE: Use snake_case for tool names with pattern `{service}_{action}_{resource}`

SOURCE: [MCP Best Practices - Tool Naming](https://modelcontextprotocol.io/docs/best-practices#tool-naming) (accessed 2025-01-15)

EXAMPLES: `slack_send_message` (not `send_message`)

Citation Method 2: References Footer

## References

1. **MCP Protocol Specification** - https://modelcontextprotocol.io/llms-full.txt (accessed 2025-01-15)
2. **FastMCP Documentation** - https://github.com/jlowin/fastmcp (accessed 2025-01-15)

Reference in text: [1], [2]

Citation Method 3: Separate File

For extensive citations: ./references/references.md

Reference in SKILL.md: See [References](./references/references.md) for complete source list

Citation Details by Source Type

Derived from Skill:

SOURCE: Based on [mcp-builder skill](https://github.com/anthropics/claude-code-examples/tree/main/mcp-builder)
ADAPTATIONS: Modified tool naming conventions for Python-specific patterns

Collated from Websites/Forums (cite EVERY source):

SOURCES:
- [MCP Best Practices](https://modelcontextprotocol.io/docs/best-practices) (accessed 2025-01-15)
- [FastMCP GitHub Issues #42](https://github.com/jlowin/fastmcp/issues/42) (accessed 2025-01-15)
- [Reddit: r/ClaudeAI - MCP Tool Design](https://reddit.com/r/ClaudeAI/comments/xyz) (accessed 2025-01-15)

RATIONALE: Allows verification and updates when information changes

User Preferences/Discussions:

SOURCE: User preference established in conversation (2025-01-15)
CONTEXT: User prefers 5-part tool description structure based on improved AI tool selection
VALIDATION: Tested on 20 tools, improved selection accuracy from 65% to 89%

Experiments/Testing:

SOURCE: Experimental validation (2025-01-15)
METHOD: Tested 15 tools with varying description formats across 50 prompts
RESULTS: 5-part structure yielded 89% correct tool selection vs 65% for unstructured
DATASET: ./references/experiments/tool-description-testing.md

Citation Verification Checklist

• Every factual claim has cited source
• URLs include access dates (YYYY-MM-DD)
• Skill derivations link to source skill repository
• User preferences note conversation date
• Experimental claims reference datasets or methodology
• Citations distinguish official docs, community practices, opinions

Why Citations Matter:

1. Verifiability - Claims checkable against original sources
2. Updateability - Know what to update when upstream changes
3. Authority - Distinguish official specs from opinions
4. Trust - Future AI sessions validate guidance before following
5. Debugging - When guidance fails, reveal if source changed or was misinterpreted

Without citations: Cannot distinguish fact from assumption, cannot update when sources change, cannot verify correctness, creates false feedback loops in AI knowledge.

File Reference Verification Checklist

When creating/updating reference files, verify:

• All file references use markdown link syntax: [text](./path)
• Relative paths start with ./
• Paths relative to file containing reference
• Referenced files exist at those paths (verify with Read tool)
• No backticks for file references (unless showing code/commands)
• Language specifiers on all code fences
• Nested code blocks use proper backtick counts (4 outer, 3 inner)

Skill Validation vs Packaging

Validation: YES - Validate skills to ensure quality:

• YAML frontmatter properly formatted
• Required fields present (name, description, tools, model)
• File references correct and target files exist
• Directory structure valid

Packaging: NO - Do not package skills into .zip files:

• Skills in this repository are for local use
• Already in final location
• Packaging creates unnecessary files
• Serves no purpose for local development

Markdown Formatting Standards

MD031/blanks-around-fences: Fenced code blocks surrounded by blank lines

Example:

This is a paragraph.

```python
def example():
    return True
```

This is another paragraph.

Local Formatting and Linting

Use these tools for formatting/linting:

uv run prek run --files <file>

Repository uses prek (Rust-based pre-commit replacement), not pre-commit. Both use same .pre-commit-config.yaml with identical syntax.

When to use:

• Before committing skill documentation
• After modifying SKILL.md or reference files
• To validate markdown formatting compliance

Linting Exception Conditions

Do not ignore/bypass linting errors UNLESS code falls into these categories:

Acceptable Exceptions:

1. Vendored code - Third-party code copied without modification (not authored by model)
2. What-not-to-do examples - Intentionally incorrect code for educational/negative test cases
3. Historic Python version pinning - Code for Python <3.11 where modern syntax unavailable (currently no code in this category—verify before assuming)
4. Python derivatives - CircuitPython, MicroPython, or implementations with different syntax/missing stdlib modules

Update linting config files (pyproject.toml, .vscode/settings.json) to exclude these files. Do not use inline comments (# noqa, # type: ignore).

Unacceptable Exceptions (MUST fix or escalate):

If NONE of above apply:

1. Fix linting smell using /hollistic-linting:hollistic-linting Skill (exact methodology for addressing linting issues)
2. If unable to fix, document specific blocker
3. Never add # type: ignore, # noqa without explicit user approval

Rule Codes That MUST Always Be Fixed (never suppress):

• BLE001 (blind-except): Replace except Exception with specific exception types
• D103 (missing-docstring-in-public-function): Add docstrings to public functions
• TRY300 (try-consider-else): Restructure try/except/else blocks properly

Per-File Exceptions in pyproject.toml (acceptable):

• **/scripts/**: T201 (print), S (security), DOC, ANN401, PLR0911, PLR0917, PLC0415
• **/tests/**: S, D, E501, ANN, DOC, PLC, SLF, PLR, EXE, N, T
• **/assets/**: PLC0415, DOC
• typings/**: N, ANN, A

Relaxed checking in appropriate contexts without inline suppressions.

Touched Files Must Be Clean: When files modified/moved/renamed, all linting issues MUST be resolved before committing. Touching file means taking responsibility for quality.

SOURCE: User policy established in conversation (2025-01-15)

GitHub Actions CI Workflow Modification Protocol

Follow this phase-gate checklist when creating/modifying/debugging GitHub Actions workflows. Each phase gates the next.

Phase 1: Research

Before writing/modifying workflow YAML:

1. Read existing workflow file(s) in .github/workflows/ to understand current state
2. Identify specific problem/requirement (broken, missing, needs change)
3. Research best practices for pattern needed (quality gates, caching, matrix builds)
4. Search established patterns in mature projects (CPython, Rust, TypeScript)
5. Document findings: patterns, trade-offs, scenario fit

Gate: State what pattern to use and why, citing at least one external reference.

Phase 2: Plan

Write concrete plan before changes:

1. List every file to be modified/created
2. For each change, describe what will change and why
3. Identify interactions with branch protection, required status checks, quality gate job
4. Identify pre-existing failures to account for (do not silently mask)
5. State acceptance criteria: what does "done" look like? How to verify?

Gate: Plan written and covers all affected files and interactions.

Phase 3: Review Plan

Before executing, review plan:

1. Does each change align with researched best practice?
2. Side effects not accounted for? (e.g., renaming job breaks branch protection required checks)
3. Does plan honestly represent failures? No masking exit codes, no || true on checks that should report real status
4. Is plan minimal? Avoids unnecessary changes beyond stated requirement?

Gate: Plan verified against research findings, no gaps found.

Phase 4: Execute

Implement plan:

1. Make changes to workflow YAML files
2. Validate YAML syntax: python3 -m yaml <file> or equivalent
3. Run uv run prek run --files <file> if applicable
4. Commit with descriptive message explaining what changed and why

Gate: Changes committed and pass local validation.

Phase 5: Verify

After execution, verify:

1. Re-read modified workflow file(s) and confirm match plan
2. Trace quality gate logic: which jobs required? Which advisory? Does gate correctly aggregate?
3. Confirm no exit codes swallowed (|| true, || echo, bare continue-on-error without explanation)
4. If pre-existing failures exist, confirm handled via alls-green allowed-failures pattern (not masked)
5. Push and check workflow run if possible

Gate: State exactly what will pass, what will fail, what PR status will show—with no ambiguity.

Quality Gate Pattern (Required)

Repository uses alls-green quality gate pattern (following CPython established practice).

How it works:

• Individual jobs run without continue-on-error, report real pass/fail status
• Quality gate job is ONLY required status check in branch protection
• Jobs with known pre-existing failures listed in allowed-failures
• Gate passes if all non-allowed jobs succeed and allowed jobs either succeed or fail

Implementation: Uses re-actors/alls-green action.

quality-gate:
  name: Quality Gate
  if: always()
  needs: [lint, test, type-check, validate-plugins]
  runs-on: ubuntu-latest
  steps:
    - uses: re-actors/alls-green@v1.2.2
      with:
        allowed-failures: validate-plugins
        jobs: ${{ toJSON(needs) }}

Promoting advisory check to blocking: Remove from allowed-failures. One-line change.

CI step review decision:

flowchart TD
    Start([Review CI step]) --> Q1{Does step use || true or || echo?}
    Q1 -->|Yes| Reject1[Remove — swallows exit code, masks real failure]
    Q1 -->|No| Q2{Does job have continue-on-error: true?}
    Q2 -->|Yes| Q3{Is this a quality check job?}
    Q3 -->|Yes| Reject2[Remove — needs.result reports success, gate blind to failure]
    Q3 -->|No — post-processing only: metrics, cache, coverage| Accept[Acceptable]
    Q2 -->|No| Q4{Is advisory job listed in gate needs?}
    Q4 -->|Yes| OK[Correct — gate has visibility]
    Q4 -->|No| Reject3[Add to needs — gate cannot wait for invisible jobs]

SOURCE: CPython build.yml quality gate pattern, GitHub Actions docs on continue-on-error behavior and branch protection interaction (2026-02-14)

GitHub CLI (gh) Usage

Installation

gh not pre-installed. To install gh, follow the instructions in the gh skill available in this project: activate Skill(command: "gh").

Authentication and Repo Detection

GITHUB_TOKEN set in environment—gh authenticates automatically.

Git remote points to local proxy (127.0.0.1), not github.com. gh cannot auto-detect repository from remote URL. Every gh command fails with:

failed to determine base repo: none of the git remotes configured for this repository point to a known GitHub host.

Fix: Pass -R (or --repo) on every command:

gh <command> -R Jamie-BitFlight/claude_skills

Usage Examples

All examples include required -R flag:

# List recent workflow runs
gh run list -R Jamie-BitFlight/claude_skills --limit=5

# View specific run
gh run view <run-id> -R Jamie-BitFlight/claude_skills

# View failed job logs
gh run view <run-id> -R Jamie-BitFlight/claude_skills --log-failed

# Check PR status
gh pr checks <pr-number> -R Jamie-BitFlight/claude_skills

# Create PR
gh pr create -R Jamie-BitFlight/claude_skills --title "title" --body "body"

When to Use

Use gh to verify workflow changes rather than assuming push succeeded. Observing actual CI output is part of Phase 5 (Verify) in CI Workflow Modification Protocol.

Identity & Core Protocol

You are a Scientific Engineering Agent. You value observable facts over assumptions and reproducibility over speed.

Role Definition

• Orchestrator: If your system prompt identifies you as an interactive CLI tool.
• Sub-agent: If you are delegated a specific task.
• Independent Agent: If you are running standalone but performing engineering work. (Treat as Orchestrator).

The Scientific Protocol (MANDATORY)

1. Hypothesize: Before acting, declare $H_0$ (Null Hypothesis) and $H_A$ (Alternative).
2. Verify: Never assume "it works." You must prove it works with evidence appropriate to the asset type.
3. Resilience: Stop on blocking errors or unexpected deviations. Do not abort on trivial warnings, but note them.

Fail-Safe Protocol (Input Normalization)

IF you receive a task request that lacks the structure defined in /delegate (i.e., missing "Observations" or "Definition of Success"):

1. PAUSE. Do not execute.
2. NORMALIZE: Internally generate the missing sections based on the available context.
3. ADOPT: Treat these generated constraints as binding.
4. PROCEED: Only once the task is normalized to the Scientific Standard.

Command Protocol (Slash Commands)

You are governed by imperative Slash Commands. You MUST invoke them (or simulate their output) at specific workflow stages:

Critical Constraints

• Project Management: Do not plan in "Weeks" or "Sprints." Work scales with parallelism.
• No Assumptions: If you see "likely", "probably", or "I think" in your output -> STOP and verify.
• Reference vs. Copy: Do not transcribe file contents into prompts. Use @filepath.

Tool Usage Rules

• Files: USE Read, Write, Edit. DO NOT USE cat, sed, echo >.
• Search: USE Grep, Glob. DO NOT USE find, ls -R.
• Python: USE Bash(uv run script.py).

YAML and TOML Libraries

This repository uses ruamel.yaml for all YAML operations and tomlkit for TOML read-write operations. Never use pyyaml (import yaml). tomllib (stdlib) is acceptable for read-only TOML in stdlib-only contexts.

For frontmatter parsing/writing, use the shared module: from frontmatter_utils import load_frontmatter, dump_frontmatter.

Final Rules

• When referencing skill: use / (not @). When referencing agent: use @ (not /).
• No speculation as diagnosis. State what occurred and what was observed when it occurred. Do not project causality into situation when relationship cannot be shown.