diff --git a/.claude/commands/agent-os/discover-standards.md b/.claude/commands/agent-os/discover-standards.md deleted file mode 100644 index b5de63ee..00000000 --- a/.claude/commands/agent-os/discover-standards.md +++ /dev/null @@ -1,261 +0,0 @@ -# Discover Standards - -Extract tribal knowledge from your codebase into concise, documented standards. - -## Important Guidelines - -- **Always use AskUserQuestion tool** when asking the user anything -- **Write concise standards** — Use minimal words. Standards must be scannable by AI agents without bloating context windows. -- **Offer suggestions** — Present options the user can confirm, choose between, or correct. Don't make them think harder than necessary. - -## Process - -### Step 1: Determine Focus Area - -Check if the user specified an area when running this command. If they did, skip to Step 2. - -If no area was specified: - -1. Analyze the codebase structure (folders, file types, patterns) -2. Identify 3-5 major areas. Examples: - - **Frontend areas:** UI components, styling/CSS, state management, forms, routing - - **Backend areas:** API routes, database/models, authentication, background jobs - - **Cross-cutting:** Error handling, validation, testing, naming conventions, file structure -3. Use AskUserQuestion to present the areas: - -``` -I've identified these areas in your codebase: - -1. **API Routes** (src/api/) — Request handling, response formats -2. **Database** (src/models/, src/db/) — Models, queries, migrations -3. **React Components** (src/components/) — UI patterns, props, state -4. **Authentication** (src/auth/) — Login, sessions, permissions - -Which area should we focus on for discovering standards? (Pick one, or suggest a different area) -``` - -Wait for user response before proceeding. - -### Step 2: Analyze & Present Findings - -Once an area is determined: - -1. Read key files in that area (5-10 representative files) -2. Look for patterns that are: - - **Unusual or unconventional** — Not standard framework/library patterns - - **Opinionated** — Specific choices that could have gone differently - - **Tribal** — Things a new developer wouldn't know without being told - - **Consistent** — Patterns repeated across multiple files - -3. Use AskUserQuestion to present findings and let user select: - -``` -I analyzed [area] and found these potential standards worth documenting: - -1. **API Response Envelope** — All responses use { success, data, error } structure -2. **Error Codes** — Custom error codes like AUTH_001, DB_002 with specific meanings -3. **Pagination Pattern** — Cursor-based pagination with consistent param names - -Which would you like to document? - -Options: -- "Yes, all of them" -- "Just 1 and 3" -- "Add: [your suggestion]" -- "Skip this area" -``` - -Wait for user selection before proceeding. - -### Step 3: Ask Why, Then Draft Each Standard - -**IMPORTANT:** For each selected standard, you MUST complete this full loop before moving to the next standard: - -1. **Ask 1-2 clarifying questions** about the "why" behind the pattern. Use your AskUserQuestion tool for this. -2. **Wait for user response** -3. **Draft the standard** incorporating their answer -4. **Confirm with user** before creating the file -5. **Create the file** if approved - -Example questions to ask (adapt based on the specific standard): - -- "What problem does this pattern solve? Why not use the default/common approach?" -- "Are there exceptions where this pattern shouldn't be used?" -- "What's the most common mistake a developer or agent makes with this?" - -**Do NOT batch all questions upfront.** Process one standard at a time through the full loop. - -### Step 4: Create the Standard File - -For each standard (after completing Step 3's Q&A): - -1. Determine the appropriate folder (create if needed): - - `api/`, `database/`, `javascript/`, `css/`, `backend/`, `testing/`, `global/` - -2. Check if a related standard file already exists — append to it if so - -3. Draft the content and use AskUserQuestion to confirm: - -``` -Here's the draft for api/response-format.md: - ---- -# API Response Format - -All API responses use this envelope: - -\`\`\`json -{ "success": true, "data": { ... } } -{ "success": false, "error": { "code": "...", "message": "..." } } -\`\`\` - -- Never return raw data without the envelope -- Error responses must include both code and message -- Success responses omit the error field entirely ---- - -Create this file? (yes / edit: [your changes] / skip) -``` - -4. Create or update the file in `agent-os/standards/[folder]/` -5. **Then repeat Steps 3-4 for the next selected standard** - -### Step 5: Update the Index - -After all standards are created: - -1. Scan `agent-os/standards/` for all `.md` files -2. For each new file without an index entry, use AskUserQuestion: - -``` -New standard needs an index entry: - File: api/response-format.md - -Suggested description: "API response envelope structure and error format" - -Accept this description? (yes / or type a better one) -``` - -3. Update `agent-os/standards/index.yml`: - -```yaml -api: - response-format: - description: API response envelope structure and error format -``` - -Alphabetize by folder, then by filename. - -### Step 6: Offer to Continue - -Use AskUserQuestion: - -``` -Standards created for [area]: -- api/response-format.md -- api/error-codes.md - -Would you like to discover standards in another area, or are we done? -``` - -## Output Location - -All standards: `agent-os/standards/[folder]/[standard].md` -Index file: `agent-os/standards/index.yml` - -## Writing Concise Standards - -Standards will be injected into AI context windows. Every word costs tokens. Follow these rules: - -- **Lead with the rule** — State what to do first, explain why second (if needed) -- **Use code examples** — Show, don't tell -- **Skip the obvious** — Don't document what the code already makes clear -- **One standard per concept** — Don't combine unrelated patterns -- **Bullet points over paragraphs** — Scannable beats readable - -**Good:** -```markdown -# Error Responses - -Use error codes: `AUTH_001`, `DB_001`, `VAL_001` - -\`\`\`json -{ "success": false, "error": { "code": "AUTH_001", "message": "..." } } -\`\`\` - -- Always include both code and message -- Log full error server-side, return safe message to client -``` - -**Bad:** -```markdown -# Error Handling Guidelines - -When an error occurs in our application, we have established a consistent pattern for how errors should be formatted and returned to the client. This helps maintain consistency across our API and makes it easier for frontend developers to handle errors appropriately... -[continues for 3 more paragraphs] -``` - -## Example: Full Loop for One Standard - -Here's how to process a single standard through the complete workflow: - -**1. Present findings (Step 2):** -``` -I found these patterns in your API code: -1. **Response Envelope** — All responses use { success, data, error } -2. **Error Codes** — Custom codes like AUTH_001 - -Which would you like to document? -``` - -User: "Both" - -**2. Ask why for first standard (Step 3):** -``` -For the Response Envelope pattern: -- What problem does this solve? Why not return raw data? -- Are there any endpoints that don't use this pattern? -``` - -User: "We use it so the frontend always knows where to find the data. All endpoints use it, no exceptions." - -**3. Draft first standard (Step 3 continued):** -``` -Here's the draft for api/response-envelope.md: - ---- -# Response Envelope - -All API responses use this structure: -\`\`\`json -{ "success": true, "data": { ... } } -{ "success": false, "error": { ... } } -\`\`\` - -- Frontend always checks `success` first, then reads `data` or `error` -- No exceptions — every endpoint uses this format ---- - -Create this file? -``` - -User: "Yes" - -**4. Create file, then move to next standard:** - -[Create the file] - -**5. Ask why for second standard (back to Step 3):** -``` -For the Error Codes pattern: -- What's the naming convention for codes? -- Where should new error codes be documented? -``` - -User: "Format is AREA_NUMBER like AUTH_001. We keep a list in the wiki." - -**6. Draft second standard, confirm, create file...** - -[Continue until all selected standards are done] - -**Key point:** Complete the full ask → draft → confirm → create cycle for each standard before starting the next one. diff --git a/.claude/commands/agent-os/index-standards.md b/.claude/commands/agent-os/index-standards.md deleted file mode 100644 index 7967c6f7..00000000 --- a/.claude/commands/agent-os/index-standards.md +++ /dev/null @@ -1,124 +0,0 @@ -# Index Standards - -Rebuild and maintain the standards index file (`index.yml`). - -## Purpose - -The index enables `/inject-standards` to suggest relevant standards without reading all files. It maps each standard to a brief description for quick matching. - -## Process - -### Step 1: Scan for Standards Files - -1. List all `.md` files in `agent-os/standards/` and its subfolders -2. Build a list of all standards organized by folder: - ``` - root/coding-style.md # Files in standards/ root use "root" as the folder name - root/naming.md - api/response-format.md - api/error-handling.md - database/migrations.md - ``` - -**Note:** `root` is a reserved keyword — it refers to `.md` files directly in `agent-os/standards/` (not in a subfolder). Do not create an actual folder named "root". - -### Step 2: Load Existing Index - -Read `agent-os/standards/index.yml` if it exists. Note which entries already have descriptions. - -### Step 3: Identify Changes - -Compare the file scan with the existing index: - -- **New files** — Standards files without index entries -- **Deleted files** — Index entries for files that no longer exist -- **Existing files** — Already indexed, keep as-is - -### Step 4: Handle New Files - -For each new standard file that needs an index entry: - -1. Read the file to understand its content -2. Use AskUserQuestion to propose a description: - -``` -New standard needs indexing: - File: api/response-format.md - -Suggested description: "API response envelope structure and error format" - -Accept? (yes / or type a better description) -``` - -Keep descriptions to **one short sentence** — they're for matching, not documentation. - -### Step 5: Handle Deleted Files - -If there are index entries for files that no longer exist: - -1. List them for the user -2. Remove them from the index automatically (no confirmation needed) - -Report: "Removed 2 stale index entries: api/old-pattern.md, testing/deprecated.md" - -### Step 6: Write Updated Index - -Generate `agent-os/standards/index.yml` with this structure: - -```yaml -folder-name: - file-name: - description: Brief description here -``` - -**Rules:** -- Alphabetize folders -- Alphabetize files within each folder -- File names without `.md` extension -- One-line descriptions only - -**Example:** -```yaml -root: - coding-style: - description: General coding style, formatting, linting rules - naming: - description: File naming, variable naming, class naming conventions - -api: - error-handling: - description: Error codes, exception handling, error response format - response-format: - description: API response envelope structure, status codes, pagination - -database: - migrations: - description: Migration file structure, naming conventions, rollback patterns -``` - -**Note:** `root` appears first and contains standards files that live directly in `agent-os/standards/` (not in subfolders). - -### Step 7: Report Results - -Summarize what changed: - -``` -Index updated: - ✓ 2 new entries added - ✓ 1 stale entry removed - ✓ 8 entries unchanged - -Total: 9 standards indexed -``` - -## When to Run - -- After manually creating or deleting standards files -- If `/inject-standards` suggestions seem out of sync -- To clean up a messy or outdated index - -**Note:** `/discover-standards` runs this automatically as its final step, so you usually don't need to call it separately after discovering standards. - -## Output - -Updates `agent-os/standards/index.yml` diff --git a/.claude/commands/agent-os/inject-standards.md b/.claude/commands/agent-os/inject-standards.md deleted file mode 100644 index f7875a61..00000000 --- a/.claude/commands/agent-os/inject-standards.md +++ /dev/null @@ -1,291 +0,0 @@ -# Inject Standards - -Inject relevant standards into the current context, formatted appropriately for the situation. - -## Usage Modes - -This command supports two modes: - -### Auto-Suggest Mode (no arguments) -``` -/inject-standards -``` -Analyzes context and suggests relevant standards. - -### Explicit Mode (with arguments) -``` -/inject-standards api # All standards in api/ -/inject-standards api/response-format # Single file -/inject-standards api/response-format api/auth # Multiple files -/inject-standards root # All standards in the root folder -/inject-standards root/naming # Single file from root folder -``` -Directly injects specified standards without suggestions. - -**Note:** `root` is a reserved keyword — it refers to `.md` files directly in `agent-os/standards/` (not in a subfolder). - -## Process - -### Step 1: Detect Context Scenario - -Before injecting standards, determine which scenario we're in. Read the current conversation and check if we're in plan mode. - -**Three scenarios:** - -1. **Conversation** — Regular chat, implementing code, answering questions -2. **Creating a Skill** — Building a `.claude/skills/` file -3. **Shaping/Planning** — In plan mode, building a spec, running `/shape-spec` - -**Detection logic:** - -- If currently in plan mode OR conversation clearly mentions "spec", "plan", "shape" → **Shaping/Planning** -- If conversation clearly mentions creating a skill, editing `.claude/skills/`, or building a reusable procedure → **Creating a Skill** -- Otherwise → **Ask to confirm** (do not assume) - -**If neither skill nor plan is clearly detected**, use AskUserQuestion to confirm: - -``` -I'll inject the relevant standards. How should I format them? - -1. **Conversation** — Read standards into our chat (for implementation work) -2. **Skill** — Output file references to include in a skill you're building -3. **Plan** — Output file references to include in a plan/spec - -Which scenario? (1, 2, or 3) -``` - -Always ask when uncertain — don't assume conversation by default. - -### Step 2: Read the Index (Auto-Suggest Mode) - -Read `agent-os/standards/index.yml` to get the list of available standards and their descriptions. - -If index.yml doesn't exist or is empty: -``` -No standards index found. Run /discover-standards first to create standards, -or /index-standards if you have standards files without an index. -``` - -### Step 3: Analyze Work Context - -Look at the current conversation to understand what the user is working on: -- What type of work? (API, database, UI, etc.) -- What technologies mentioned? -- What's the goal? - -### Step 4: Match and Suggest - -Match index descriptions against the context. Use AskUserQuestion to present suggestions: - -``` -Based on your task, these standards may be relevant: - -1. **api/response-format** — API response envelope structure, status codes -2. **api/error-handling** — Error codes, exception handling, error responses -3. **global/naming** — File naming, variable naming conventions - -Inject these standards? (yes / just 1 and 3 / add: database/migrations / none) -``` - -Keep suggestions focused — typically 2-5 standards. Don't overwhelm with too many options. - -### Step 5: Inject Based on Scenario - -Format the output differently based on the detected scenario: - ---- - -#### Scenario: Conversation - -Read the standards and announce them: - -``` -I've read the following standards as they are relevant to what we're working on: - ---- Standard: api/response-format --- - -[full content of the standard file] - ---- End Standard --- - ---- Standard: api/error-handling --- - -[full content of the standard file] - ---- End Standard --- - -**Key points:** -- All API responses use { success, data, error } envelope -- Error codes follow AUTH_xxx, DB_xxx pattern -``` - ---- - -#### Scenario: Creating a Skill - -First, use AskUserQuestion to determine how to include the standards: - -``` -How should these standards be included in your skill? - -1. **References** — Add @ file paths that point to the standards (keeps skill lightweight, standards stay in sync) -2. **Copy content** — Paste the full standards content into the skill (self-contained, but won't update if standards change) - -Which approach? (1 or 2) -``` - -**If References (option 1):** - -``` -Be sure to include references to the following standards files in the appropriate location in the file(s) that make up this skill: - -@agent-os/standards/api/response-format.md -@agent-os/standards/api/error-handling.md -@agent-os/standards/global/naming.md - -These standards cover: -- API response envelope structure, status codes -- Error codes, exception handling, error responses -- File naming, variable naming conventions -``` - -**If Copy content (option 2):** - -``` -Include the following standards content in your skill: - ---- Standard: api/response-format --- - -[full content of the standard file] - ---- End Standard --- - ---- Standard: api/error-handling --- - -[full content of the standard file] - ---- End Standard --- - -These standards cover: -- API response envelope structure, status codes -- Error codes, exception handling, error responses -- File naming, variable naming conventions -``` - ---- - -#### Scenario: Shaping/Planning - -First, use AskUserQuestion to determine how to include the standards: - -``` -How should these standards be included in your plan? - -1. **References** — Add @ file paths that point to the standards (keeps plan lightweight, standards stay in sync) -2. **Copy content** — Paste the full standards content into the plan (self-contained, but won't update if standards change) - -Which approach? (1 or 2) -``` - -**If References (option 1):** - -``` -Be sure to include references to the following standards files in the appropriate location in the plan we're building: - -@agent-os/standards/api/response-format.md -@agent-os/standards/api/error-handling.md -@agent-os/standards/global/naming.md - -These standards cover: -- API response envelope structure, status codes -- Error codes, exception handling, error responses -- File naming, variable naming conventions -``` - -**If Copy content (option 2):** - -``` -Include the following standards content in your plan: - ---- Standard: api/response-format --- - -[full content of the standard file] - ---- End Standard --- - ---- Standard: api/error-handling --- - -[full content of the standard file] - ---- End Standard --- - -These standards cover: -- API response envelope structure, status codes -- Error codes, exception handling, error responses -- File naming, variable naming conventions -``` - ---- - -### Step 6: Surface Related Skills (Conversation scenario only) - -When in conversation scenario, check if `.claude/skills/` exists and contains related skills: - -``` -Related Skills you might want to use: -- create-api-endpoint — Scaffolds new API endpoints following these standards -``` - -Don't invoke skills automatically — just surface them for awareness. - ---- - -## Explicit Mode - -When arguments are provided, skip the suggestion step but still detect scenario. - -### Step 1: Detect Scenario - -Same as auto-suggest mode. - -### Step 2: Parse Arguments - -Arguments can be: -- **Folder name** — `api` → inject all `.md` files in `agent-os/standards/api/` -- **Folder/file** — `api/response-format` → inject `agent-os/standards/api/response-format.md` -- **Root folder** — `root` → inject all `.md` files directly in `agent-os/standards/` (not in subfolders) -- **Root file** — `root/naming` → inject `agent-os/standards/naming.md` - -Multiple arguments inject multiple standards. - -### Step 3: Validate - -Check that specified files/folders exist. If not: - -``` -Standard not found: api/nonexistent - -Available standards in api/: -- response-format -- error-handling -- authentication - -Did you mean one of these? -``` - -### Step 4: Inject Based on Scenario - -Same formatting as auto-suggest mode, based on detected scenario. - ---- - -## Tips - -- **Run early** — Inject standards at the start of a task, before implementation -- **Be specific** — If you know which standards apply, use explicit mode -- **Check the index** — If suggestions seem wrong, run `/index-standards` to rebuild -- **Keep standards concise** — Injected standards consume tokens; shorter is better - -## Integration - -This command is called internally by `/shape-spec` to inject relevant standards during planning. You can also invoke it directly anytime you need standards in context. diff --git a/.claude/commands/agent-os/plan-product.md b/.claude/commands/agent-os/plan-product.md deleted file mode 100644 index bd8bf16e..00000000 --- a/.claude/commands/agent-os/plan-product.md +++ /dev/null @@ -1,204 +0,0 @@ -# Plan Product - -Establish foundational product documentation through an interactive conversation. Creates mission, roadmap, and tech stack files in `agent-os/product/`. - -## Important Guidelines - -- **Always use AskUserQuestion tool** when asking the user anything -- **Keep it lightweight** — gather enough to create useful docs without over-documenting -- **One question at a time** — don't overwhelm with multiple questions - -## Process - -### Step 1: Check for Existing Product Docs - -Check if `agent-os/product/` exists and contains any of these files: -- `mission.md` -- `roadmap.md` -- `tech-stack.md` - -**If any files exist**, use AskUserQuestion: - -``` -I found existing product documentation: -- mission.md: [exists/missing] -- roadmap.md: [exists/missing] -- tech-stack.md: [exists/missing] - -Would you like to: -1. Start fresh (replace all) -2. Update specific files -3. Cancel - -(Choose 1, 2, or 3) -``` - -If option 2, ask which files to update and only gather info for those. -If option 3, stop here. - -**If no files exist**, proceed to Step 2. - -### Step 2: Gather Product Vision (for mission.md) - -Use AskUserQuestion: - -``` -Let's define your product's mission. - -**What problem does this product solve?** - -(Describe the core problem or pain point you're addressing) -``` - -After they respond, use AskUserQuestion: - -``` -**Who is this product for?** - -(Describe your target users or audience) -``` - -After they respond, use AskUserQuestion: - -``` -**What makes your solution unique?** - -(What's the key differentiator or approach?) -``` - -### Step 3: Gather Roadmap (for roadmap.md) - -Use AskUserQuestion: - -``` -Now let's outline your development roadmap. - -**What are the must-have features for launch (MVP)?** - -(List the core features needed for the first usable version) -``` - -After they respond, use AskUserQuestion: - -``` -**What features are planned for after launch?** - -(List features you'd like to add in future phases, or say "none yet") -``` - -### Step 4: Establish Tech Stack (for tech-stack.md) - -First, check if `agent-os/standards/global/tech-stack.md` exists. - -**If the tech-stack standard exists**, read it and use AskUserQuestion: - -``` -I found a tech stack standard in your standards: - -[Summarize the key technologies from global/tech-stack.md] - -Does this project use the same tech stack, or does it differ? - -1. Same as standard (use as-is) -2. Different (I'll specify) - -(Choose 1 or 2) -``` - -If they choose option 1, use the standard's content for tech-stack.md. -If they choose option 2, proceed to ask them to specify (see below). - -**If no tech-stack standard exists** (or they chose option 2 above), use AskUserQuestion: - -``` -**What technologies does this project use?** - -Please describe your tech stack: -- Frontend: (e.g., React, Vue, vanilla JS, or N/A) -- Backend: (e.g., Rails, Node, Django, or N/A) -- Database: (e.g., PostgreSQL, MongoDB, or N/A) -- Other: (hosting, APIs, tools, etc.) -``` - -### Step 5: Generate Files - -Create the `agent-os/product/` directory if it doesn't exist. - -Generate each file based on the information gathered: - -#### mission.md - -```markdown -# Product Mission - -## Problem - -[Insert what problem this product solves - from Step 2] - -## Target Users - -[Insert who this product is for - from Step 2] - -## Solution - -[Insert what makes the solution unique - from Step 2] -``` - -#### roadmap.md - -```markdown -# Product Roadmap - -## Phase 1: MVP - -[Insert must-have features for launch - from Step 3] - -## Phase 2: Post-Launch - -[Insert planned future features - from Step 3, or "To be determined" if they said none yet] -``` - -#### tech-stack.md - -```markdown -# Tech Stack - -[Organize the tech stack information into logical sections] - -## Frontend - -[Frontend technologies, or "N/A" if not applicable] - -## Backend - -[Backend technologies, or "N/A" if not applicable] - -## Database - -[Database choice, or "N/A" if not applicable] - -## Other - -[Other tools, hosting, services - or omit this section if nothing mentioned] -``` - -### Step 6: Confirm Completion - -After creating all files, output to user: - -``` -✓ Product documentation created: - - agent-os/product/mission.md - agent-os/product/roadmap.md - agent-os/product/tech-stack.md - -Review these files to ensure they accurately capture your product vision. -You can edit them directly or run /plan-product again to update. -``` - -## Tips - -- If the user provides very brief answers, that's fine — the docs can be expanded later -- If they want to skip a section, create the file with a placeholder like "To be defined" -- The `/shape-spec` command will read these files when planning features, so having them populated helps with context diff --git a/.claude/commands/agent-os/shape-spec.md b/.claude/commands/agent-os/shape-spec.md deleted file mode 100644 index e06d4853..00000000 --- a/.claude/commands/agent-os/shape-spec.md +++ /dev/null @@ -1,267 +0,0 @@ -# Shape Spec - -Gather context and structure planning for significant work. **Run this command while in plan mode.** - -## Important Guidelines - -- **Always use AskUserQuestion tool** when asking the user anything -- **Offer suggestions** — Present options the user can confirm, adjust, or correct -- **Keep it lightweight** — This is shaping, not exhaustive documentation - -## Prerequisites - -This command **must be run in plan mode**. - -**Before proceeding, check if you are currently in plan mode.** - -If NOT in plan mode, **stop immediately** and tell the user: - -``` -Shape-spec must be run in plan mode. Please enter plan mode first, then run /shape-spec again. -``` - -Do not proceed with any steps below until confirmed to be in plan mode. - -## Process - -### Step 1: Clarify What We're Building - -Use AskUserQuestion to understand the scope: - -``` -What are we building? Please describe the feature or change. - -(Be as specific as you like — I'll ask follow-up questions if needed) -``` - -Based on their response, ask 1-2 clarifying questions if the scope is unclear. Examples: -- "Is this a new feature or a change to existing functionality?" -- "What's the expected outcome when this is done?" -- "Are there any constraints or requirements I should know about?" - -### Step 2: Gather Visuals - -Use AskUserQuestion: - -``` -Do you have any visuals to reference? - -- Mockups or wireframes -- Screenshots of similar features -- Examples from other apps - -(Paste images, share file paths, or say "none") -``` - -If visuals are provided, note them for inclusion in the spec folder. - -### Step 3: Identify Reference Implementations - -Use AskUserQuestion: - -``` -Is there similar code in this codebase I should reference? - -Examples: -- "The comments feature is similar to what we're building" -- "Look at how src/features/notifications/ handles real-time updates" -- "No existing references" - -(Point me to files, folders, or features to study) -``` - -If references are provided, read and analyze them to inform the plan. - -### Step 4: Check Product Context - -Check if `agent-os/product/` exists and contains files. - -If it exists, read key files (like `mission.md`, `roadmap.md`, `tech-stack.md`) and use AskUserQuestion: - -``` -I found product context in agent-os/product/. Should this feature align with any specific product goals or constraints? - -Key points from your product docs: -- [summarize relevant points] - -(Confirm alignment or note any adjustments) -``` - -If no product folder exists, skip this step. - -### Step 5: Surface Relevant Standards - -Read `agent-os/standards/index.yml` to identify relevant standards based on the feature being built. - -Use AskUserQuestion to confirm: - -``` -Based on what we're building, these standards may apply: - -1. **api/response-format** — API response envelope structure -2. **api/error-handling** — Error codes and exception handling -3. **database/migrations** — Migration patterns - -Should I include these in the spec? (yes / adjust: remove 3, add frontend/forms) -``` - -Read the confirmed standards files to include their content in the plan context. - -### Step 6: Generate Spec Folder Name - -Create a folder name using this format: -``` -YYYY-MM-DD-HHMM-{feature-slug}/ -``` - -Where: -- Date/time is current timestamp -- Feature slug is derived from the feature description (lowercase, hyphens, max 40 chars) - -Example: `2026-01-15-1430-user-comment-system/` - -**Note:** If `agent-os/specs/` doesn't exist, create it when saving the spec folder. - -### Step 7: Structure the Plan - -Now build the plan with **Task 1 always being "Save spec documentation"**. - -Present this structure to the user: - -``` -Here's the plan structure. Task 1 saves all our shaping work before implementation begins. - ---- - -## Task 1: Save Spec Documentation - -Create `agent-os/specs/{folder-name}/` with: - -- **plan.md** — This full plan -- **shape.md** — Shaping notes (scope, decisions, context from our conversation) -- **standards.md** — Relevant standards that apply to this work -- **references.md** — Pointers to reference implementations studied -- **visuals/** — Any mockups or screenshots provided - -## Task 2: [First implementation task] - -[Description based on the feature] - -## Task 3: [Next task] - -... - ---- - -Does this plan structure look right? I'll fill in the implementation tasks next. -``` - -### Step 8: Complete the Plan - -After Task 1 is confirmed, continue building out the remaining implementation tasks based on: -- The feature scope from Step 1 -- Patterns from reference implementations (Step 3) -- Constraints from standards (Step 5) - -Each task should be specific and actionable. - -### Step 9: Ready for Execution - -When the full plan is ready: - -``` -Plan complete. When you approve and execute: - -1. Task 1 will save all spec documentation first -2. Then implementation tasks will proceed - -Ready to start? (approve / adjust) -``` - -## Output Structure - -The spec folder will contain: - -``` -agent-os/specs/{YYYY-MM-DD-HHMM-feature-slug}/ -├── plan.md # The full plan -├── shape.md # Shaping decisions and context -├── standards.md # Which standards apply and key points -├── references.md # Pointers to similar code -└── visuals/ # Mockups, screenshots (if any) -``` - -## shape.md Content - -The shape.md file should capture: - -```markdown -# {Feature Name} — Shaping Notes - -## Scope - -[What we're building, from Step 1] - -## Decisions - -- [Key decisions made during shaping] -- [Constraints or requirements noted] - -## Context - -- **Visuals:** [List of visuals provided, or "None"] -- **References:** [Code references studied] -- **Product alignment:** [Notes from product context, or "N/A"] - -## Standards Applied - -- api/response-format — [why it applies] -- api/error-handling — [why it applies] -``` - -## standards.md Content - -Include the full content of each relevant standard: - -```markdown -# Standards for {Feature Name} - -The following standards apply to this work. - ---- - -## api/response-format - -[Full content of the standard file] - ---- - -## api/error-handling - -[Full content of the standard file] -``` - -## references.md Content - -```markdown -# References for {Feature Name} - -## Similar Implementations - -### {Reference 1 name} - -- **Location:** `src/features/comments/` -- **Relevance:** [Why this is relevant] -- **Key patterns:** [What to borrow from this] - -### {Reference 2 name} - -... -``` - -## Tips - -- **Keep shaping fast** — Don't over-document. Capture enough to start, refine as you build. -- **Visuals are optional** — Not every feature needs mockups. -- **Standards guide, not dictate** — They inform the plan but aren't always mandatory. -- **Specs are discoverable** — Months later, someone can find this spec and understand what was built and why. diff --git a/.github/CHANGELOG.md b/.github/CHANGELOG.md index c14ff587..1c1ac42f 100644 --- a/.github/CHANGELOG.md +++ b/.github/CHANGELOG.md @@ -26,13 +26,13 @@ Use this format for new updates: - Narrowed `internal-gateway-operational-flow` to delegate unresolved idea work visibly to the new gateway and consume validated Definition Brief handoffs for `plan` without repeating ideation or its critical pass. - Added guided decision interview semantics: evidence-first discovery, iterative numbered question blocks through `grill-me`, visible defaults, compact decision ledger, proportional depth, and checkpoint states. - Retired the standalone `idea-refine` skill immediately after extracting its useful shaping frameworks and evaluation criteria into `internal-gateway-idea` references, preserving its upstream license and removing the competing runtime entrypoint. -- Updated adjacent routing owners (`internal-agent-support-next-step`, `internal-agent-support-lane-change-engine`, `internal-gateway-simple-task`, `internal-gateway-critical-master`) to recognize the new gateway in handoffs and lane-change recommendations. +- Updated adjacent gateway routing owners to recognize the new gateway in handoffs and lane-change recommendations. - Updated `.github/agents/README.md`, `.github/README.md`, `INTERNAL_CONTRACT.md`, `docs`, wrapper-alignment, mode-contracts, subagent-patterns, home-sync catalog, token benchmarks, and regression tests for the four-gateway model. ## 2026-05-19 - Migrated the repository to the skill-first Copilot model under the approved architecture-migration exception: replacement owners, routing, references, and validators moved first, `.github/instructions/` was removed afterward, `internal-aws-serverless` was replaced by `internal-aws-lambda`, and no standards release was published as part of the repository edit. -- Added the three canonical gateway wrapper agents `.github/agents/internal-gateway-operational-flow.agent.md`, `.github/agents/internal-gateway-critical-master.agent.md`, and `.github/agents/internal-gateway-simple-task.agent.md`, soft-deprecated the four prior operational wrappers as non-invocable compatibility stubs, and realigned active prompt, README, lane-change, wrapper-alignment, internal-contract, test, and inventory contracts to the new model. +- Added the canonical gateway wrapper agents, soft-deprecated prior operational wrappers as non-invocable compatibility stubs, and realigned active prompt, README, lane-change, wrapper-alignment, internal-contract, test, and inventory contracts to the new model. ## 2026-05-16 diff --git a/.github/INVENTORY.md b/.github/INVENTORY.md index 5831aae4..926e3e00 100644 --- a/.github/INVENTORY.md +++ b/.github/INVENTORY.md @@ -34,11 +34,6 @@ This file is the exact path inventory for the live GitHub Copilot catalog in thi - `.github/skills/addyosmani-code-review-and-quality/SKILL.md` - `.github/skills/addyosmani-code-simplification/SKILL.md` -- `.github/skills/agent-os-discover-standards/SKILL.md` -- `.github/skills/agent-os-index-standards/SKILL.md` -- `.github/skills/agent-os-inject-standards/SKILL.md` -- `.github/skills/agent-os-plan-product/SKILL.md` -- `.github/skills/agent-os-shape-spec/SKILL.md` - `.github/skills/anthropic-docx/SKILL.md` - `.github/skills/anthropic-pdf/SKILL.md` - `.github/skills/anthropic-pptx/SKILL.md` @@ -62,8 +57,6 @@ This file is the exact path inventory for the live GitHub Copilot catalog in thi - `.github/skills/awesome-copilot-security-review/SKILL.md` - `.github/skills/grill-me/SKILL.md` - `.github/skills/internal-agent-creator/SKILL.md` -- `.github/skills/internal-agent-support-lane-change-engine/SKILL.md` -- `.github/skills/internal-agent-support-next-step/SKILL.md` - `.github/skills/internal-aws-governance/SKILL.md` - `.github/skills/internal-aws-lambda/SKILL.md` - `.github/skills/internal-aws-mcp-research/SKILL.md` @@ -119,7 +112,6 @@ This file is the exact path inventory for the live GitHub Copilot catalog in thi - `.github/skills/internal-python-project/SKILL.md` - `.github/skills/internal-python-script/SKILL.md` - `.github/skills/internal-python/SKILL.md` -- `.github/skills/internal-review-ai-resources/SKILL.md` - `.github/skills/internal-review-code/SKILL.md` - `.github/skills/internal-review-high-level/SKILL.md` - `.github/skills/internal-skill-creator/SKILL.md` @@ -141,6 +133,8 @@ This file is the exact path inventory for the live GitHub Copilot catalog in thi - `.github/skills/mattpocock-setup-matt-pocock-skills/SKILL.md` - `.github/skills/mattpocock-tdd/SKILL.md` - `.github/skills/mattpocock-to-spec/SKILL.md` +- `.github/skills/mattpocock-to-tickets/SKILL.md` +- `.github/skills/mattpocock-triage/SKILL.md` - `.github/skills/mattpocock-wayfinder/SKILL.md` - `.github/skills/mattpocock-writing-great-skills/SKILL.md` - `.github/skills/openai-docs/SKILL.md` @@ -193,18 +187,10 @@ These vendor-prefixed imported document skills remain support-only depth for rep ## Agents -- `.github/agents/internal-gateway-critical-master.agent.md` -- `.github/agents/internal-gateway-execute-plans.agent.md` -- `.github/agents/internal-gateway-idea.agent.md` -- `.github/agents/internal-gateway-review-code.agent.md` -- `.github/agents/internal-gateway-review-generic.agent.md` -- `.github/agents/internal-gateway-simple-task.agent.md` - `.github/agents/local-sync-external-resources.agent.md` - `.github/agents/local-sync-install-ai-resources.agent.md` - `.github/agents/local-sync-repos.agent.md` ## Prompts -- `.github/prompts/internal-architecture-md-creator.prompt.md` -- `.github/prompts/internal-mega-review.prompt.md` -- `.github/prompts/internal-review-ai-resources.prompt.md` +No prompt files currently ship in the live catalog. diff --git a/.github/README.md b/.github/README.md index 0c6f25c3..3aeeb11b 100644 --- a/.github/README.md +++ b/.github/README.md @@ -9,12 +9,5 @@ customization assets maintained in `cloud-strategy.github`. ## Agents -- Canonical repository-owned gateway agents: - `internal-gateway-idea`, `internal-gateway-review-generic`, - `internal-gateway-critical-master`, `internal-gateway-simple-task` -- Specialist repository-owned review agents: - `internal-gateway-review-code` for code-focused review before merge or follow-up action. -- Approved retained plans under tmp/superpowers/plans/ execute through - `internal-gateway-execute-plans`. -- When extra provenance helps, offer it as an optional follow-up detail and accept - number-only replies. +- Repository-local sync agents are documented in [`agents/README.md`](agents/README.md). +- Reusable gateway and review workflows live under [`skills/`](skills/). diff --git a/.github/agents/README.md b/.github/agents/README.md index 81ad20ba..5c681939 100644 --- a/.github/agents/README.md +++ b/.github/agents/README.md @@ -1,26 +1,11 @@ # Agents Catalog -This folder contains Copilot wrapper agents for repository-owned operations plus -repo-only sync workflows. +This folder contains Copilot wrapper agents for repo-only sync workflows. -## Agent-Owned Core - -- `internal-gateway-idea`: owns substantive idea definition, - critical challenge, and retained planning before execution. -- `internal-gateway-review-generic`: owns generic defect-first review for non-code and - mixed artifacts before fixes. -- `internal-gateway-review-code`: owns dedicated code-focused review for source, tests, - scripts, build metadata, dependency metadata, and code diffs. -- `internal-gateway-critical-master`: owns pressure testing. -- `internal-gateway-simple-task`: owns concrete execution and approved retained-plan consumption. - -## Active Gateway Agents +## Active Agents | Agent | Use when | | --- | --- | -| `internal-gateway-idea` | A vague idea or unresolved goal needs definition and retained planning. | -| `internal-gateway-review-generic` | A concrete non-code or mixed artifact needs defect-first review before fixes. | -| `internal-gateway-review-code` | A concrete code target needs dedicated code review before merge or follow-up action. | -| `internal-gateway-critical-master` | A proposal or plan needs pressure before action. | -| `internal-gateway-simple-task` | A concrete low-to-medium-risk task can finish through one focused lane. | -| `internal-gateway-execute-plans` | An approved retained plan under tmp/superpowers/plans/ is ready for execution. | +| `local-sync-external-resources` | Declared external-resource refreshes need preparation, audit, planning, or application. | +| `local-sync-install-ai-resources` | Repository-owned AI resources or the portable `AGENTS.md` baseline need local-home synchronization. | +| `local-sync-repos` | Consumer repositories need managed baseline alignment or drift assessment. | diff --git a/.github/agents/internal-gateway-critical-master.agent.md b/.github/agents/internal-gateway-critical-master.agent.md deleted file mode 100644 index f25fae00..00000000 --- a/.github/agents/internal-gateway-critical-master.agent.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -name: internal-gateway-critical-master -description: "Use this agent when a repository-owned plan, proposal, decision, or assumption set needs critical challenge before action." -tools: ["read", "search"] -disable-model-invocation: true -agents: [] ---- - -# Internal Gateway Critical Master - -## Core Skill - -- `internal-gateway-critical-master` -- Keep the full critical record internal and emit only the localized compact - card defined by the skill's output contract. diff --git a/.github/agents/internal-gateway-execute-plans.agent.md b/.github/agents/internal-gateway-execute-plans.agent.md deleted file mode 100644 index 3824ff1f..00000000 --- a/.github/agents/internal-gateway-execute-plans.agent.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -name: internal-gateway-execute-plans -description: "Use this agent when an approved retained plan under tmp/superpowers/plans/ is ready for execution or resume." -tools: ["read", "edit", "search", "execute"] -agents: [] -handoffs: [] ---- - -# Internal Gateway Execute Plans - -## Core Skill - -- `internal-gateway-execute-plans` diff --git a/.github/agents/internal-gateway-idea.agent.md b/.github/agents/internal-gateway-idea.agent.md deleted file mode 100644 index fa389f8c..00000000 --- a/.github/agents/internal-gateway-idea.agent.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -name: internal-gateway-idea -description: "Use this agent when a repository-owned request starts with a vague idea, unclear goal, unresolved option set, or needs substantive definition, convergence, critical challenge, and retained planning before execution." -tools: ["read", "edit", "search", "execute", "web"] -agents: [] -handoffs: - - label: "Next step: Execute retained plan" - agent: "internal-gateway-execute-plans" - prompt: "Execute only the approved retained plan under tmp/superpowers/plans/ left by the idea definition above. Verify the plan path is exact and the user has approved execution." - send: false - - label: "Next step: Pressure-test decision" - agent: "internal-gateway-critical-master" - prompt: "Pressure-test the reasoning, assumptions, or failure modes behind the retained planning decision." - send: false - - label: "Next step: Review target" - agent: "internal-gateway-review-generic" - prompt: "The work above became review-oriented rather than planning-oriented. Use internal-gateway-review-generic to review the concrete artifact and stop before fixes." - send: false ---- - -# Internal Gateway Idea - -## Core Skill - -- `internal-gateway-idea` diff --git a/.github/agents/internal-gateway-review-code.agent.md b/.github/agents/internal-gateway-review-code.agent.md deleted file mode 100644 index b33b3053..00000000 --- a/.github/agents/internal-gateway-review-code.agent.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -name: internal-gateway-review-code -description: "Senior repository code reviewer for source code, tests, scripts, build files, dependency files, and code-focused diffs before merge or follow-up action." -tools: ["read", "search", "execute"] -disable-model-invocation: true -agents: [] ---- - -# Senior Code Reviewer - -You are an experienced Staff Engineer conducting a thorough code review. Your role is to evaluate the proposed changes and provide actionable, categorized feedback. - -## Review Framework - -Evaluate every change across these five dimensions: - -### 1. Correctness -- Does the code do what the spec/task says it should? -- Are edge cases handled (null, empty, boundary values, error paths)? -- Do the tests actually verify the behavior? Are they testing the right things? -- Are there race conditions, off-by-one errors, or state inconsistencies? - -### 2. Readability -- Can another engineer understand this without explanation? -- Are names descriptive and consistent with project conventions? -- Is the control flow straightforward (no deeply nested logic)? -- Is the code well-organized (related code grouped, clear boundaries)? - -### 3. Architecture -- Does the change follow existing patterns or introduce a new one? -- If a new pattern, is it justified and documented? -- Are module boundaries maintained? Any circular dependencies? -- Is the abstraction level appropriate (not over-engineered, not too coupled)? -- Are dependencies flowing in the right direction? - -### 4. Security -- Is user input validated and sanitized at system boundaries? -- Are secrets kept out of code, logs, and version control? -- Is authentication/authorization checked where needed? -- Are queries parameterized? Is output encoded? -- Any new dependencies with known vulnerabilities? - -### 5. Performance -- Any N+1 query patterns? -- Any unbounded loops or unconstrained data fetching? -- Any synchronous operations that should be async? -- Any unnecessary re-renders (in UI components)? -- Any missing pagination on list endpoints? - -## Repository Review Contract - -- Resolve the concrete code target first: diff, pull request, changed file list, source file, test file, script, build file, dependency file, or generated-code boundary. -- Read the spec, task description, or stated intent before judging implementation details when that evidence exists. -- Review tests before implementation when tests are present because they reveal intended behavior and coverage gaps. -- Keep the review code-focused. Prefer `internal-gateway-review-generic` when the primary target is an AI resource, workflow, policy, plan, documentation package, or mixed non-code artifact. -- Do not edit files, apply fixes, author plans, or route to peer agents. The user decides what to do after reading the report. -- Every Critical, Important, and Suggestion finding must reference a concrete file path and line when line evidence is available. -- If evidence is incomplete, mark the item as uncertain and recommend investigation instead of guessing. - -## Critical Counter-Analysis - -Before presenting the final report, pressure-test the review with `internal-gateway-critical-master` as the counter-analysis lens. Challenge severity, confidence, false positives, missing evidence, contrary explanations, validation coverage, and whether a no-finding claim is supported. - -If the counter-analysis exposes a material gap, reopen the review and return `Verdict: NEEDS INVESTIGATION` instead of presenting an unsupported approval or request-changes verdict. - -## Output Format - -Categorize every finding: - -**Critical** - Must fix before merge (security vulnerability, data loss risk, broken functionality) - -**Important** - Should fix before merge (missing test, wrong abstraction, poor error handling) - -**Suggestion** - Consider for improvement (naming, code style, optional optimization) - -## Review Output Template - -```markdown -## Review Summary - -**Verdict:** APPROVE | REQUEST CHANGES | NEEDS INVESTIGATION - -**Overview:** [1-2 sentences summarizing the change and overall assessment] - -### Critical Issues -- [File:line] [Description, impact, and recommended fix] - -### Important Issues -- [File:line] [Description, impact, and recommended fix] - -### Suggestions -- [File:line] [Description and recommended fix when useful] - -### Sound Decisions / Preserved Conventions -- [Evidence-backed note explaining why a risky-looking choice is acceptable or why a local convention should be preserved] - -### Verification Story -- Tests reviewed: [yes/no, observations] -- Build verified: [yes/no] -- Security checked: [yes/no, observations] -- Validation missing: [specific command, test, or review gap] - -### Critical Counter-Analysis Result -- Result: [passed/reopened] -- Notes: [severity changes, false positives removed, missing evidence, or residual uncertainty] - -### Residual Risk -- [Specific remaining risk, or "No material residual risk found within reviewed scope."] - -### Next Decision -- [accept | patch | investigate | accept with risk] -``` - -## Rules - -1. Review the tests first - they reveal intent and coverage. -2. Read the spec or task description before reviewing code. -3. Every Critical and Important finding should include a specific fix recommendation. -4. Do not approve code with Critical issues. -5. Include `Sound Decisions / Preserved Conventions` only when it is evidence-bearing or decision-useful. -6. If you are uncertain about something, say so and suggest investigation rather than guessing. -7. Counter-analyze the report before presenting it to the user. -8. Stop after the review report; do not apply fixes. - -## Composition - -- **Invoke directly when:** the user asks for a review of a specific code change, source file, test file, script, build file, dependency file, generated-code boundary, or pull request. -- **Prefer `internal-gateway-review-generic` when:** the target is non-code, an AI resource, workflow, policy, plan, documentation package, or a mixed artifact where code is not the primary surface. -- **Do not invoke from another persona.** If deeper security, testing, or architecture ownership would change the decision, surface that as a recommendation in your report instead of delegating. diff --git a/.github/agents/internal-gateway-review-generic.agent.md b/.github/agents/internal-gateway-review-generic.agent.md deleted file mode 100644 index 825f44e1..00000000 --- a/.github/agents/internal-gateway-review-generic.agent.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -name: internal-gateway-review-generic -description: "Use this agent when repository-owned work needs a defect-first review of a concrete non-code or mixed artifact, workflow, AI resource, policy, plan, bundle, or review package before acceptance or follow-up action." -tools: ["read", "search", "execute"] -disable-model-invocation: true -agents: [] ---- - -# Internal Gateway Review - -## Role - -You are the repository generic review gateway. Review concrete non-code or mixed repository-owned work and return a decision-ready report after counter-validating your analysis. You are not a dedicated code reviewer, fixer, planner, or execution lane. - -## Review Framework - -Evaluate the target through the dimensions that apply to its surface: - -### 1. Intent And Scope -- Is the review target concrete enough to judge? -- Does the artifact match the stated goal, audience, and repository ownership boundary? -- Are exclusions, assumptions, and decision points explicit? - -### 2. Correctness And Contract Fit -- Does the artifact preserve repository policy, catalog contracts, routing rules, and consumer expectations? -- Are names, paths, frontmatter, metadata, and referenced assets accurate? -- Does the artifact avoid stale references, hollow dependencies, and owner drift? - -### 3. Risk And Regression -- Could the change break sync, validation, runtime routing, review behavior, or downstream consumers? -- Are security, privacy, secret-handling, or governance expectations weakened? -- Are rollout, compatibility, and reversibility risks understood? - -### 4. Ownership And Maintainability -- Is there one clear owner for the behavior? -- Is the artifact concise enough to maintain without duplicating another owner? -- Does it avoid unnecessary procedure, broad skill fan-out, and ambiguous handoffs? - -### 5. Validation And Evidence -- What validation has already been run? -- What validation is still missing? -- Is the final verdict supported by direct evidence rather than broad inference? - -## Generic Review Surfaces - -- **AI resources:** agents, skills, prompts, instructions, bundle siblings, catalog entries, sync behavior, and customization drift. -- **Workflows:** CI, repository automation, release or review flows, operational handoffs, and validation paths. -- **Policies and documentation:** AGENTS, READMEs, governance notes, standards, instructions, and decision records. -- **Plans and review packages:** retained plans, specs, audit packages, issue analysis, and decision-support reports. -- **Mixed artifacts:** any target where code is secondary evidence inside a broader repository-owned artifact. - -Prefer `internal-gateway-review-code` when the target is purely code: source, tests, scripts, build files, dependency files, generated-code boundaries, or a code-focused diff. - -## Critical Counter-Analysis - -Before presenting the final report, pressure-test findings with `internal-gateway-critical-master` as the counter-analysis lens. Challenge severity, confidence, false positives, contrary evidence, scope narrowing, validation coverage, residual risk, and whether the report supports a clear user decision. - -If the counter-analysis exposes a material gap, reopen the review and return `review gate: reopen` instead of presenting an unsupported no-finding claim or final verdict. - -## Output Format - -Use this report shape: - -```markdown -## Review Summary - -**Verdict:** APPROVE | REQUEST CHANGES | NEEDS INVESTIGATION - -**Review Gate:** satisfied | reopen - -**Overview:** [1-2 sentences summarizing the target, reviewed surface, and overall assessment] - -### Blocking Findings -- [Path or evidence point] [Finding, impact, severity, confidence, and recommended fix direction] - -### Important Findings -- [Path or evidence point] [Finding, impact, severity, confidence, and recommended fix direction] - -### Suggestions -- [Path or evidence point] [Improvement that is useful but not blocking] - -### Sound Decisions / Preserved Conventions -- [Evidence-backed note explaining why a risky-looking choice is acceptable or why a local convention should be preserved] - -### Verification Story -- Evidence reviewed: [files, diff, prompt, catalog, workflow, or retained package] -- Validation reviewed: [commands or checks already run] -- Validation missing: [specific command, check, or manual review gap] - -### Critical Counter-Analysis Result -- Result: [passed/reopened] -- Notes: [severity changes, false positives removed, missing evidence, or residual uncertainty] - -### Residual Risk -- [Specific remaining risk, or "No material residual risk found within reviewed scope."] - -### Next Decision -- [accept | patch | investigate | plan separately | accept with risk] -``` - -## Review Rules - -- Resolve the concrete target first: diff, file list, pull request, workflow, skill, agent, prompt, policy, plan, document, bundle, or retained review package. -- Read the smallest evidence needed to understand intent, changed surface, validation status, and risk. -- Classify the primary review surface before judging it: code, workflow, AI resource, policy or documentation, plan, or mixed. -- Report findings first, ordered by severity. Prefer a few high-confidence findings over broad commentary. -- Test the contrary explanation before reporting a finding: intended behavior, local convention, compatibility need, generated output, explicit user scope, or validator coverage. -- Include `Sound Decisions / Preserved Conventions` only when it is evidence-bearing or decision-useful. -- Do not edit files, apply fixes, author plans, or move into an execution lane. The user decides what to do after reading the report. -- Stop after the review report. - -## Routing Rules - -- Use this agent when the user asks for review, audit, critique, merge-readiness assessment, prompt or agent review, workflow review, policy review, plan review, or artifact risk assessment. -- Use this agent when the review target is not purely code or when the surface is mixed. -- Prefer `internal-gateway-review-code` when the requested review is specifically for source code, tests, scripts, build files, dependency files, or a code-focused diff. -- Do not use this agent when the user has already approved implementation, remediation, or execution. -- Do not use this agent when there is no concrete review target; ask for the artifact, diff, file, PR, or package to review. -- Do not delegate to peer agents or hand off to fix lanes. Name likely follow-up owners only as report context when that helps the user choose a next step. diff --git a/.github/agents/internal-gateway-simple-task.agent.md b/.github/agents/internal-gateway-simple-task.agent.md deleted file mode 100644 index 27ca1cfb..00000000 --- a/.github/agents/internal-gateway-simple-task.agent.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -name: internal-gateway-simple-task -description: "Use this agent when a concrete low-to-medium-risk repository-owned task can be answered, edited, diagnosed, or validated quickly in one bounded run, and should stop with reason when complexity or cost breaks that boundary." -tools: ["read", "edit", "search", "execute", "web"] -agents: [] ---- - -# Internal Gateway Simple Task - -## Core Skill - -- `internal-gateway-simple-task` diff --git a/.github/agents/local-sync-external-resources.agent.md b/.github/agents/local-sync-external-resources.agent.md index 71d73226..54d6c40d 100644 --- a/.github/agents/local-sync-external-resources.agent.md +++ b/.github/agents/local-sync-external-resources.agent.md @@ -50,6 +50,17 @@ contract instead of reproducing its procedure here. - When changing the sync tooling itself, do not refresh or modify imported resources in the same task. +## Post-Apply Validation Boundaries + +1. After repository mutation, run the closest focused validation as its own next action. +2. Stop on the first failure and report the failing evidence. +3. Only after the focused check passes, run remaining declared validations and + a bounded worktree summary in one subsequent terminal action with + short-circuit semantics. +4. Keep separately authorized, interactive, or networked operations outside + that consolidated action. +5. Do not repeat unchanged command output across progress and final reports. + ## Outcome Report the core skill's complete result without optimistic compression: diff --git a/.github/agents/local-sync-repos.agent.md b/.github/agents/local-sync-repos.agent.md index 6245c59c..bc637556 100644 --- a/.github/agents/local-sync-repos.agent.md +++ b/.github/agents/local-sync-repos.agent.md @@ -22,7 +22,7 @@ Use this agent for route selection, mode selection, approval posture, and bounda - Use this agent for consumer-repository baseline propagation, drift assessment, `plan`, and explicit `apply` runs. - Select `apply` only on explicit request, after the current evidence shows a conflict-safe plan and no unmanaged target-local cleanup is being implied. -- Do not use this agent for source-side catalog governance, external-resource refreshes, home AI sync, or managed-scope redesign; recommend `local-sync-external-resources`, `local-agent-sync-install-ai-resources`, or `internal-gateway-idea` as appropriate. +- Do not use this agent for source-side catalog governance, external-resource refreshes, home AI sync, or managed-scope redesign; recommend the corresponding source-side owner instead. ## Boundary Definition diff --git a/.github/instructions/internal-json.instructions.md b/.github/instructions/internal-json.instructions.md index f18a1696..d3b45a11 100644 --- a/.github/instructions/internal-json.instructions.md +++ b/.github/instructions/internal-json.instructions.md @@ -8,10 +8,14 @@ excludeAgent: "cloud-agent" This file is optimized for Copilot code review and should produce only evidenced findings on matching changed files. -- Verify JSON is valid and structurally consistent with adjacent files in the same family. -- Flag key renames or type changes that break existing consumers. -- Check required fields are present and optional fields are used consistently. -- Report duplicate keys, ambiguous defaults, or contradictory values. -- Verify identifiers, enums, and policy values match repository conventions. -- Flag ordering or formatting drift only when it harms diff readability or tooling. -- Check for embedded secrets or sensitive values that must not be committed. +- Use the bundle checker for `JSON_BOM`, `JSON_ENCODING`, `JSON_SYNTAX`, + `JSON_DUPLICATE_KEY`, `JSON_NON_FINITE`, `JSON_UNSAFE_INTEGER`, + `JSON_NUMBER_RANGE`, and `JSON_UNPAIRED_SURROGATE` findings. +- Review BOM/UTF-8 handling, duplicate keys, strict grammar, and numeric interoperability + at the format boundary. +- Remember that object order is not semantic in JSON; report ordering only + when a consuming owner explicitly defines presentation requirements. +- Separately review schema-sensitive key or type changes, required properties, + identifiers or enums, and content meaning against an evidenced local contract. +- Report secret exposure and contradictory defaults when the changed file + provides evidence; route broader domain semantics to the owning instruction. diff --git a/.github/instructions/internal-makefile.instructions.md b/.github/instructions/internal-makefile.instructions.md index 724685b1..bea8d3be 100644 --- a/.github/instructions/internal-makefile.instructions.md +++ b/.github/instructions/internal-makefile.instructions.md @@ -8,10 +8,16 @@ excludeAgent: "cloud-agent" This file is optimized for Copilot code review and should produce only evidenced findings on matching changed files. -- Verify target names and dependencies reflect deterministic build order. -- Flag missing `.PHONY` declarations for non-file targets. -- Check recipe commands for shell safety and clear failure behavior. -- Report hidden environment coupling that breaks reproducible runs. -- Verify variable defaults and overrides are explicit and non-ambiguous. -- Check parallelism-sensitive targets for race-prone shared artifacts. -- Flag undocumented side effects in commonly used targets. +- Use the bundle checker and distinguish its `phonydeclared` finding from + review-only Make behavior. +- Check target prerequisites, recipe prefix characters, `.PHONY`, variables, + and `$ / $$` expansion intent. +- Review order-only prerequisites, parallelism, recursive Make, and shared + artifacts when target ordering or concurrency matters. +- Separately review deterministic build order, hidden environment coupling, + failure behavior, and undocumented side effects when the changed file + provides evidence. +- Treat shell semantics and domain behavior as human review concerns; the + checker never invokes recipes. +- Remember that `make -n` is not a generic safety boundary: recipes may still + have observable expansion or tool-specific behavior. diff --git a/.github/instructions/internal-markdown.instructions.md b/.github/instructions/internal-markdown.instructions.md index 6ed89f10..485ad09a 100644 --- a/.github/instructions/internal-markdown.instructions.md +++ b/.github/instructions/internal-markdown.instructions.md @@ -8,10 +8,15 @@ excludeAgent: "cloud-agent" This file is optimized for Copilot code review and should produce only evidenced findings on matching changed files. -- Verify content is concise, technically accurate, and free of contradictory guidance. -- Flag stale paths, commands, or references that do not match repository reality. -- Check heading structure for clear scanability and stable document navigation. -- Report duplicated policy text that should remain in a single canonical owner. -- Verify examples are minimal, valid, and aligned with current contracts. -- Flag language that implies behavior not enforced by code, tests, or validators. -- Check links and anchors for resolution and maintenance risk. +- Use the bundle checker for high-confidence structural findings: MD011 for + reversed links, MD042 for empty links, MD051 for invalid fragments, MD052 + for undefined references, and MD053 for duplicate or unused references. +- Check fences, local links/fragments, paths, reference definitions, and + heading structure without treating a Markdown dialect as universal. +- Record dialect awareness when CommonMark, GitHub Flavored Markdown, or a + tool-specific extension changes the interpretation. +- Separately review technical claims, commands, paths, and examples against + repository evidence; report stale references, contradictory guidance, or + behavior presented as enforced without support from code, tests, or validators. +- Report duplicated policy only when its canonical owner is evident. Leave + external targets, editorial judgment, and broader policy ownership to their owners. diff --git a/.github/instructions/internal-python.instructions.md b/.github/instructions/internal-python.instructions.md index 454d253d..9e4b7fcd 100644 --- a/.github/instructions/internal-python.instructions.md +++ b/.github/instructions/internal-python.instructions.md @@ -17,7 +17,7 @@ This file is optimized for Copilot code review and should produce only evidenced - Flag manual formatting churn that fights the repository formatter; when Ruff is configured, prefer `ruff format` and Ruff diagnostics over subjective style edits. - Report dependency usage that is unpinned, unnecessary for the change, or unjustified for the data volume and import or install cost. - Flag vendored libraries, wheelhouses, copied site-packages, or fallback dependency mirrors. -- Flag new external dependencies that are missing hash-locked pins in the owning requirements file. +- Preserve the repository-declared dependency manager. For pip requirements, require exact pins and hashes in the owning requirements file; for another declared dependency manager, require its canonical lock artifact and frozen or locked validation command. - When behavior changes, verify docs and output contracts stay aligned: filenames, produced artifacts, columns, and other user-visible output details must match reality. - Check tests for deterministic coverage of changed behavior. - Flag test setup that bypasses the repository's shared runner, pytest rootdir or testpaths contract, or declared interpreter or virtualenv setup without a reproducibility reason. diff --git a/.github/instructions/internal-yaml.instructions.md b/.github/instructions/internal-yaml.instructions.md index 6537c0e6..67ce3f90 100644 --- a/.github/instructions/internal-yaml.instructions.md +++ b/.github/instructions/internal-yaml.instructions.md @@ -8,10 +8,15 @@ excludeAgent: "cloud-agent" This file is optimized for Copilot code review and should produce only evidenced findings on matching changed files. -- Verify YAML is syntactically valid with stable indentation and scalar usage. -- Flag duplicate keys, ambiguous merges, or anchor misuse. -- Check schema-sensitive fields for type and key-name correctness. -- Report values that change runtime behavior without explicit intent. -- Verify environment-specific overrides do not leak across scopes. -- Flag embedded secrets, credentials, or sensitive identifiers. -- Check comments and structure only when they affect maintainability or correctness. +- Run the bundle-owned checker for syntax and the `key-duplicates` rule before + reporting automated findings. +- Check indentation, tabs, scalar styles, block scalar/chomping behavior, and + encoding at the format boundary. +- Review anchors/aliases and merge behavior for explicit, portable intent. +- Treat schema/tag routing as a handoff to the owning platform or domain + instruction; generic YAML validity is not schema validation. +- Separately review secret exposure, runtime-changing values, + environment-scope leaks, and domain-policy changes when the changed file + provides evidence. +- Keep those review-only findings distinct from parser findings and route + schema-specific conclusions to the owning platform or domain instruction. diff --git a/.github/prompts/internal-architecture-md-creator.prompt.md b/.github/prompts/internal-architecture-md-creator.prompt.md deleted file mode 100644 index 3b9b9956..00000000 --- a/.github/prompts/internal-architecture-md-creator.prompt.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -name: "internal-architecture-md-creator" -agent: "internal-gateway-simple-task" -description: "Generate or refresh a repository `docs/architecture.md` contract from repository evidence." -argument-hint: "Optional target repository path plus optional focus, constraints, or chat-language preference" ---- - - - -Target repository: -${input:repository:Repository path or name. Leave empty to target the current repository root.} - -Optional focus areas: -${input:focus:Optional focus such as runtime flow, IaC layout, CI/CD, testing, security boundaries, monorepo split, or AI-agent risk surface.} - -Optional constraints or exclusions: -${input:constraints:Optional non-negotiables, ADRs to preserve, sections to skip, or areas to leave unchanged.} - -Chat response language: -${input:language:Match the current chat unless explicitly overridden. Retained artifact content must stay in English.} - -Use these sources first: - -- [AGENTS.md](../../AGENTS.md) -- [.github/copilot-instructions.md](../copilot-instructions.md) -- [.github/INVENTORY.md](../INVENTORY.md) -- [.github/agents/internal-gateway-simple-task.agent.md](../agents/internal-gateway-simple-task.agent.md) -- [.github/skills/internal-gateway-simple-task/SKILL.md](../skills/internal-gateway-simple-task/SKILL.md) - -Execution contract: - -1. Resolve `repository` to a real workspace path. Ask only if the repository is - still unresolved after obvious path checks. -2. Inspect the repository before writing. Prefer evidence from source code, - config, workflows, tests, IaC, and existing docs. -3. Create or update only `docs/architecture.md`. -4. Keep retained artifact content, headings, tables, and filenames in English. - The chat summary may follow the requested chat language. -5. Do not invent architecture. Mark unsupported claims as `Unknown / To verify`. -6. If `docs/architecture.md` already exists, refresh it in place and remove - claims that current evidence no longer supports. -7. If the request conflicts with the observed architecture, explain the conflict - before editing. - -Required artifact outline: - -```md -# Architecture - -## 1. Purpose -## 2. System overview -## 3. Current vs intended architecture -## 4. Technology stack -## 5. Repository map -## 6. Architectural boundaries -## 7. Dependency rules -## 8. Key flows -## 9. Configuration and environment -## 10. Testing and validation -## 11. Architectural decisions visible in the repo -## 12. AI-agent working rules -## 13. Last verified -## 14. Unknown / To verify -``` - -Output rules: - -- Keep the document concise, evidence-based, and stable enough for repeated - AI-agent use. -- Use source paths when a claim is `Documented`, `Evidenced`, or `Inferred`. -- Never expose secret values. -- Suggest `AGENTS.md` or `.github/copilot-instructions.md` snippet updates only - in chat when the repository would clearly benefit. Do not edit those files - unless explicitly requested. diff --git a/.github/prompts/internal-mega-review.prompt.md b/.github/prompts/internal-mega-review.prompt.md deleted file mode 100644 index 280e60d0..00000000 --- a/.github/prompts/internal-mega-review.prompt.md +++ /dev/null @@ -1,333 +0,0 @@ ---- -name: "internal-mega-review" -agent: "internal-gateway-review-generic" -description: "Run a complete advisor-only mega review for one or more repositories and write split English analysis under each repo tmp/" -argument-hint: "Repository paths or names; optional focus and constraints; retained output is English" ---- - - - -Repositories to review: -${input:repositories:List one or more repository names or paths. Use one per line when possible.} - -Optional focus areas: -${input:focus:Optional focus such as security, governance, architecture, testing, automation, documentation, AI-readiness, or migration risk} - -Optional constraints or exclusions: -${input:constraints:Optional non-negotiables, exclusions, prior findings to preserve, or rollout concerns} - -Output language: -${input:language:Match chat language unless explicitly overridden. If you want to force one, write Italian or English.} - -Retained analysis content, headings, tables, and artifact filenames must stay in English. - -Use these standards-repository sources first for governance, evidence, and split-output discipline: - -- [AGENTS.md](../../AGENTS.md) -- [.github/copilot-instructions.md](../copilot-instructions.md) -- [.github/INVENTORY.md](../INVENTORY.md) -- [.github/agents/internal-gateway-review-generic.agent.md](../agents/internal-gateway-review-generic.agent.md) -- [.github/agents/internal-gateway-critical-master.agent.md](../agents/internal-gateway-critical-master.agent.md) -- [.github/skills/internal-gateway-writing-plans/SKILL.md](../skills/internal-gateway-writing-plans/SKILL.md) - -For this mega-review prompt, the English retained artifact contract below overrides any legacy non-English filename examples in those sources. - -Then run a complete, analysis-only mega review with these rules. - -## 1. Mission - -Review one or more repositories as a pragmatic technical advisor. - -- Do not apply fixes. -- Do not edit production files. -- Do not rename, move, or delete real repository assets. -- Write analysis artifacts only under `tmp/`. -- Keep the output concise, operational, evidence-based, written in English, and ready to guide later implementation work. - -## 2. Repository Resolution - -For each item in `repositories`: - -1. Resolve it to a real repository path in the current workspace or obvious sibling path. -2. If the path is ambiguous or missing, stop and ask only for the unresolved repository. -3. Treat each resolved repository independently before producing any cross-repo synthesis. - -## 3. Output Locations - -For each target repository, write the retained analysis under: - -- `/tmp/superpowers/mega-review/` - -If more than one repository is reviewed, also create a global cross-repo package under: - -- `tmp/superpowers/mega-review-global/` - -If the target `tmp/superpowers/mega-review/` folder already exists: - -- Preserve the previous analysis. -- Do not rewrite it wholesale. -- Add only missing coverage, corrections, or newly discovered findings in a separate numbered file such as `05-review-addendum.md`, or in a numbered addendum inside the relevant domain folder. -- Update `01-executive-summary.md` only when the executive summary is materially outdated. -- Do not create new non-English filenames. If a prior package uses legacy non-English filenames, preserve those files and continue with English-named delta files unless the user explicitly asks for migration. - -If no prior review exists, create a fresh split review package. - -## 4. Required Method - -For each repository: - -1. Start with a compact inventory before judging the repository. -2. Derive the technology stack only from repository evidence on disk. -3. Adapt the review to the observed stack and domain. -4. If the repository contains technologies, frameworks, or tooling not explicitly anticipated here, extend the review to cover them from first principles instead of skipping them. -5. Never invent technologies, workflows, or controls that are not present. -6. Prefer repository evidence over assumptions, and explicit uncertainty over false confidence. -7. When a repository-owned bundle owner such as `SKILL.md` materially affects a finding, inspect bundle siblings (`references/`, `scripts/`, `assets/`, and `agents/openai.yaml`) or mark the intentional non-action. - -## 5. Inventory First - -Before findings, produce a compact repository inventory covering what is actually present, for example: - -- Languages -- Frameworks and runtime tooling -- IaC tooling such as Terraform, Terragrunt, CloudFormation, Pulumi, Helm, Kubernetes manifests, Rego, policy files, or equivalent -- CI/CD systems and workflow triggers -- Security controls and scanning surfaces -- Test and validation surfaces -- Documentation and runbooks -- Governance and audit artifacts -- AI-facing files such as `AGENTS.md`, prompt files, instructions, skills, memory, or repository-specific agent guidance -- Repository purpose and likely owner, if inferable from evidence - -If an area is not present or not verifiable, say so. - -## 6. Review Dimensions - -For each repository, review at least these dimensions when relevant to the observed stack: - -- Security and least privilege -- Architecture and design clarity -- Code and script quality -- Automation and CI/CD -- Testing and validation -- Documentation and operational readiness -- Governance and auditability -- AI-readiness -- Cleanup, dead assets, drift, and standardization opportunities - -Also adapt to domain-specific concerns such as IAM, RBAC, policy-as-code, cloud governance, FinOps, GitHub org governance, platform operations, or repo-governance when those are actually present. - -## 7. Evidence Rule - -Every finding must cite concrete evidence such as: - -- A specific path -- A specific workflow -- A repeated pattern observed in files or directories -- A missing but expected validation surface relative to the detected stack -- An explicit contrast with another reviewed repository when doing cross-repo analysis - -If a claim cannot be tied to concrete evidence, move it to open questions or blockers instead of classifying it as a finding. - -## 8. Finding Format - -For each material finding, use this structure: - -### Finding Title - -- Severity: Critical | Medium | Low -- Category: Security | Architecture | Automation | Testing | Documentation | Governance | AI-readiness | Cleanup -- Classification: Must | Should | Could | Won't for now -- Evidence: specific file, directory, workflow, or repeated pattern -- Problem: what is wrong -- Impact: why it matters -- Proposed action: what to do later -- Estimated effort: S | M | L -- Invasiveness: low | medium | high -- Less invasive alternative: if applicable - -## 9. Required Output Shape Per Repository - -Use split numbered files, not one monolithic document. The package MUST be organized by reader context: a small top-level entrypoint plus two domain folders, one for cloud infrastructure and one for application engineering. Avoid duplicating the same finding across files; assign it to the domain where the owner will act. - -Every retained file MUST begin with a short `Purpose:` blockquote explaining what the file is for. - -Required top-level retained output per repository: - -- `01-executive-summary.md` -- `02-inventory-and-current-state.md` -- `03-remediation-plan.md` -- `04-consistency-gate.md` -- `open-questions-and-blockers.md` - -Required `cloud-infra/` output: - -- `cloud-infra/01-overview.md` -- `cloud-infra/02-architecture.md` -- `cloud-infra/03-iac-code-and-scripts.md` -- `cloud-infra/04-automation-and-cicd.md` -- `cloud-infra/05-governance-and-auditability.md` -- `cloud-infra/06-security-and-compliance.md` -- `cloud-infra/07-remediation-plan.md` - -Required `application-engineering/` output: - -- `application-engineering/01-overview.md` -- `application-engineering/02-architecture.md` -- `application-engineering/03-code-and-script-quality.md` -- `application-engineering/04-testing-and-validation.md` -- `application-engineering/05-automation-and-cicd.md` -- `application-engineering/06-security-and-dependency-hygiene.md` -- `application-engineering/07-remediation-plan.md` - -If the repository already has a retained review package, preserve the prior files and add complement files such as: - -- `05-review-addendum.md` at top level, or a numbered addendum inside the relevant domain folder. - -`01-executive-summary.md` must always exist as the entrypoint for a fresh review package and must link to the domain folder overview files, the top-level remediation index, consistency gate, and open questions file. - -Each domain detail file must contain: - -1. What this file is for -2. Scope for this repository -3. Critical findings in that category (using the Finding Format from section 8) -4. Medium findings in that category -5. Low findings in that category -6. Quick wins specific to that category, if any -7. Open questions specific to that category, if any - -If a domain detail file has no meaningful issue, the file must still exist and explicitly say: `No relevant finding observed.` so reviewers know the dimension was assessed. - -`03-remediation-plan.md` is a short routing index only. It must link to `cloud-infra/07-remediation-plan.md` and `application-engineering/07-remediation-plan.md`. - -The two domain remediation plan files hold their own priorities, quick wins, strategic moves, and file actions. Do not create separate backlog, quick-win, and file-action files unless the user explicitly asks for them. - -## 10. Required Tables - -Use compact tables where relevant. Tables should normally have 3 or 4 columns and MUST NOT exceed 5 columns unless the user explicitly asks for a wider table. Prefer bullets for details that would make a table hard to read. - -Priority plan: - -| Priority | Area | Work item | First action | -| --- | --- | --- | --- | - -Allowed priorities: - -- P0 = critical risk or major blocker -- P1 = high value or high risk -- P2 = important but not urgent -- P3 = cleanup or optional optimization - -File actions: - -| Action | Target | Reason | Effort | -| --- | --- | --- | --- | - -Allowed actions: - -- keep -- delete -- merge -- split -- rename -- compress -- move -- create -- automate -- standardize - -Quick wins: - -| Action | Owner area | Target | -| --- | --- | --- | - -## 11. Cross-Repo Output When Reviewing More Than One Repository - -If more than one repository is in scope, also produce a global split review under `tmp/superpowers/mega-review-global/`. - -Minimum global output: - -- `01-executive-summary.md` -- `02-consistency-cross-repo.md` -- `03-security-and-automation-gaps.md` -- `04-global-roadmap.md` -- `05-global-ai-readiness.md` -- `06-recommended-global-standard.md` -- `open-questions-and-blockers.md` - -Optional when complementing an existing global package: - -- `07-review-addendum.md` -- `08-critical-master-consistency-gate.md` - -Global review coverage must include: - -1. Executive summary -2. Global maturity matrix -3. Cross-repo consistency -4. Common security gaps -5. Common automation opportunities -6. Standardization candidates -7. Provider-specific or domain-specific differences that should remain local -8. Global AI-readiness assessment -9. Recommended repository standard -10. Global prioritized roadmap - -Use this compact maturity matrix: - -| Repo | Strengths | Main gaps | Top next step | -| --- | --- | --- | --- | - -Use this compact roadmap table: - -| Priority | Initiative | Repositories | First step | -| --- | --- | --- | --- | - -## 12. Review Discipline - -- Be severe but useful. -- Prefer pragmatic changes over aesthetic refactors. -- Recommend invasive changes only when the benefit is clearly justified. -- For every invasive proposal, explain why it is necessary, the less invasive option, the risk of doing it, the risk of not doing it, and the estimated effort. -- Do not overuse `Must`. -- Do not confuse temporary uncertainty with a verified problem. - -## 13. Existing Analysis Handling - -If the repository already contains prior analysis under `tmp/`: - -- Read it first. -- Preserve what is still valid. -- Only add missing sections, corrected evidence, or newly observed findings. -- Avoid duplicating the same backlog item unless the evidence has materially changed. -- Keep newly created retained artifacts in English even when prior retained analysis used another language or legacy filenames. - -## 14. Final Consistency Gate - -Before finishing, validate the resulting analysis against the challenge posture defined in: - -- [.github/agents/internal-gateway-critical-master.agent.md](../agents/internal-gateway-critical-master.agent.md) - -Run a brief consistency gate that answers: - -1. What in the final review is most likely correct? -2. What is most likely incorrect, contradictory, overstated, or insufficiently verified? -3. Which findings should be downgraded, reframed, or moved to open questions? - -If useful, save that gate as a retained artifact in the global package or in the reviewed repository package. - -## 15. Final Quality Bar - -Before stopping, verify that the retained output is: - -- Concrete -- Verifiable -- Non-generic -- Non-destructive -- Adapted to the observed repositories and stacks -- Split into multiple files -- Written with English retained content and filenames -- Useful for follow-up implementation work -- Explicit about impact, priority, effort, and uncertainty - -If a repository cannot support a complete review because key evidence is missing, say exactly what is not verifiable from the repository and continue with the parts that are verifiable. diff --git a/.github/prompts/internal-review-ai-resources.prompt.md b/.github/prompts/internal-review-ai-resources.prompt.md deleted file mode 100644 index dbaed877..00000000 --- a/.github/prompts/internal-review-ai-resources.prompt.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -name: "internal-review-ai-resources" -agent: "internal-gateway-review-generic" -description: "Review repository-owned AI resources, referenced assets, and flow behavior across AGENTS.md and .github" -argument-hint: "Target one file, one or more folders, the full AI catalog, or an existing retained report package" ---- - - - -Primary goal: -${input:goal:Describe why this review is needed and what decision it must support} - -Review target: -${input:target:List one resource, several folders, the full AI catalog, or an existing retained report package} - -Consumer surfaces: -${input:consumers:List relevant consumers such as GitHub Copilot, Codex, local sync, or write infer from repository evidence} - -Known local assumptions or concerns: -${input:assumptions:List internal wrappers, imported-resource posture, known drift, prior findings, or write infer from repository evidence} - -Desired depth: -${input:depth:Choose concise, detailed, or exhaustive; default to detailed when unsure} - -Constraints and exclusions: -${input:constraints:List no-touch areas, rollout constraints, evidence limits, or explicit exclusions} - -Output preference: -${input:output:Write chat-only, retained report under tmp/, or infer from target size} - -Use these repository sources first: - -- [AGENTS.md](../../AGENTS.md) -- [.github/copilot-instructions.md](../copilot-instructions.md) -- [.github/INVENTORY.md](../INVENTORY.md) -- [INTERNAL_CONTRACT.md](../../INTERNAL_CONTRACT.md) -- [.github/agents/internal-gateway-review-generic.agent.md](../agents/internal-gateway-review-generic.agent.md) -- [.github/skills/internal-review-ai-resources/SKILL.md](../skills/internal-review-ai-resources/SKILL.md) - -Then use `internal-review-ai-resources` as the reusable qualitative owner for -profile selection, target coverage, lifecycle checks, report shape, and bundle -review depth. - -Review target may be one resource path, one or more folders, the full AI -catalog, or an existing retained review package under `tmp/`. Use the skill to -select `focused`, `bundle`, `catalog`, or `retained-report` and keep the review -analysis-only. - -If the target is a skill bundle, treat the bundle root plus existing -`references/`, `scripts/`, `assets/`, and `agents/openai.yaml` as in scope. - -Load additional repository skills only when the target or its evidence path -needs their owner rules. In particular, load -`internal-copilot-audit` only when overlap, hollow references, stale contracts, -naming drift, or governance drift findings are needed. Do not load every skill -only because it exists. - -Use `LESSONS_LEARNED.md` only when it is explicitly in the target, referenced by -an in-scope resource, or needed to verify a retained-learning claim. Treat it as -non-canonical retained evidence until codified in the smallest valid owner. - -The review is analysis-only. Do not modify the reviewed resources. If retained -analysis is needed, write only under `tmp/`. - -Do not name vendor-specific reasoning engines or compare them. Review consumer -surfaces, contracts, and repository behavior instead. - -Do not produce an encyclopedic review. Include only real problems, important -tradeoffs, recommended decisions, blocking uncertainties, and high-ROI quick -wins. If a resource has no meaningful problem, use an explicit keep result and -move on. - -Do not propose new technology before diagnosing the existing repository -correctly. - -## Language Rules - -- Write the final analysis and summary in the language of the current chat. -- If the current chat language is ambiguous or mixed, prefer Italian. -- Keep file paths, enum values, evidence labels, status labels, and command names - exactly as requested. diff --git a/.github/scripts/benchmark_skill_tokens.py b/.github/scripts/benchmark_skill_tokens.py index cc203524..aab2f00a 100644 --- a/.github/scripts/benchmark_skill_tokens.py +++ b/.github/scripts/benchmark_skill_tokens.py @@ -116,7 +116,7 @@ def build_scenario_report(root: Path) -> list[dict[str, Any]]: "Define idea and critical": [ GATEWAY_SKILL, "grill-me", "internal-gateway-critical-master", ], - "Plan handoff": [GATEWAY_SKILL, "internal-gateway-writing-plans", "internal-agent-support-next-step"], + "Plan handoff": [GATEWAY_SKILL, "internal-gateway-writing-plans"], "Approved apply-plan": [GATEWAY_SKILL, "internal-gateway-execute-plans"], "Review counter-check": [ REVIEW_COUNTERCHECK_SKILL, @@ -131,7 +131,7 @@ def build_scenario_report(root: Path) -> list[dict[str, Any]]: "Mandatory critical pass": [ IDEA_GATEWAY_SKILL, "internal-gateway-critical-master", ], - "Visible handoff": [IDEA_GATEWAY_SKILL, "internal-agent-support-next-step"], + "Visible handoff": [IDEA_GATEWAY_SKILL], } GATEWAY_OUTPUT_FIELD_SCENARIOS: dict[str, list[str]] = { diff --git a/.github/scripts/lib/catalog_checks.py b/.github/scripts/lib/catalog_checks.py index 24142d83..bc39ff04 100644 --- a/.github/scripts/lib/catalog_checks.py +++ b/.github/scripts/lib/catalog_checks.py @@ -8,8 +8,6 @@ from .inventory import collect_inventory_sections, parse_inventory_markdown from .shared import ( - IGNORED_SYNC_FILENAMES, - IGNORED_SYNC_PARTS, IMPORTED_ASSET_OVERRIDES_PATH, INVENTORY_PATH, LEGACY_AGENT_TOOL_IDS, diff --git a/.github/scripts/lib/token_risks.py b/.github/scripts/lib/token_risks.py index e09c9787..77df6e52 100644 --- a/.github/scripts/lib/token_risks.py +++ b/.github/scripts/lib/token_risks.py @@ -21,8 +21,6 @@ INVENTORY_LINE_PATTERN = re.compile(r"^- `?\.github/[^`]+`?(?::|\s*$)") IMPORTED_SKILL_DESCRIPTION_LIMIT = 500 ESTIMATED_TOKEN_BYTES = 4 -DELEGATED_REVIEW_PROMPT_PATH = ".github/prompts/internal-review-ai-resources.prompt.md" -DELEGATED_REVIEW_PROMPT_TOKEN_TARGET = 1100 ROOT_ALWAYS_ON_PATHS = ("AGENTS.md",) ROOT_ALWAYS_ON_TOKEN_TARGET = 4000 COPILOT_REVIEW_PATH = ".github/copilot-instructions.md" @@ -54,18 +52,12 @@ GATEWAY_CORE_SKILL_PATH = ".github/skills/internal-gateway-idea/SKILL.md" GATEWAY_CORE_BYTE_BUDGET = 16286 GATEWAY_REQUIRED_CONTEXT_BYTE_BUDGET = 30000 -GATEWAY_UNIVERSAL_PRELOAD_MARKERS = ( - "Always preload only `grill-me` and `internal-agent-support-next-step`.", -) - - def detect_token_risks(root: Path) -> list[Finding]: findings: list[Finding] = [] findings.extend(check_root_policy_overlap(root)) findings.extend(check_agents_operational_procedure_markers(root)) findings.extend(check_root_always_on_budget(root)) findings.extend(check_copilot_review_budget(root)) - findings.extend(check_delegated_review_prompt_budget(root)) findings.extend(check_review_baseline_window(root)) findings.extend(check_inventory_dumps(root)) findings.extend(check_duplicate_markdown_bodies(root)) @@ -75,7 +67,6 @@ def detect_token_risks(root: Path) -> list[Finding]: findings.extend(check_internal_root_policy_overlap(root)) findings.extend(check_paired_agent_skill_overlap(root)) findings.extend(check_gateway_core_budget(root)) - findings.extend(check_gateway_universal_preload_regression(root)) return sorted(findings, key=finding_sort_key) @@ -133,32 +124,6 @@ def check_copilot_review_budget(root: Path) -> list[Finding]: ] -def check_delegated_review_prompt_budget(root: Path) -> list[Finding]: - path = root / DELEGATED_REVIEW_PROMPT_PATH - if not path.exists(): - return [] - - estimated_tokens = estimate_tokens(path) - if estimated_tokens <= DELEGATED_REVIEW_PROMPT_TOKEN_TARGET: - return [] - - return [ - Finding( - severity="non-blocking", - code="delegated-review-prompt-budget", - path=DELEGATED_REVIEW_PROMPT_PATH, - message=( - "The delegated AI resource review prompt exceeds its soft token target " - f"({estimated_tokens} estimated tokens, target {DELEGATED_REVIEW_PROMPT_TOKEN_TARGET})." - ), - suggestion=( - "Keep user inputs and the analysis-only boundary in the prompt, but move reusable workflow " - "detail into .github/skills/internal-review-ai-resources/." - ), - ) - ] - - def check_agents_operational_procedure_markers(root: Path) -> list[Finding]: path = root / "AGENTS.md" if not path.exists(): @@ -579,35 +544,6 @@ def check_gateway_core_budget(root: Path) -> list[Finding]: ] -def check_gateway_universal_preload_regression(root: Path) -> list[Finding]: - path = root / GATEWAY_CORE_SKILL_PATH - if not path.exists(): - return [] - - text = read_text(path) - found_markers = [ - marker for marker in GATEWAY_UNIVERSAL_PRELOAD_MARKERS if marker in text - ] - if not found_markers: - return [] - - return [ - Finding( - severity="non-blocking", - code="gateway-universal-preload-regression", - path=GATEWAY_CORE_SKILL_PATH, - message=( - "The operational-flow core still contains universal preload instructions " - f"that should be phase-local: {', '.join(repr(m) for m in found_markers)}." - ), - suggestion=( - "Load grill-me when Gate 0 activates and internal-agent-support-next-step " - "when a transition package is needed; do not preload universally." - ), - ) - ] - - def extract_section_bullets(text: str, heading: str) -> list[str]: bullets: list[str] = [] inside_section = False diff --git a/.github/scripts/run.sh b/.github/scripts/run.sh index 1c122019..44c31f00 100755 --- a/.github/scripts/run.sh +++ b/.github/scripts/run.sh @@ -34,12 +34,12 @@ Tools: github_catalog_validation analyze_copilot_debug_log benchmark_skill_tokens - build_inventory - check_catalog_consistency - audit_copilot_catalog - detect_token_risks + build_inventory + check_catalog_consistency + audit_copilot_catalog + detect_token_risks sync_home_ai_resources - validate_critical_output + validate_critical_output validate_internal_skills EOF } diff --git a/.github/skills/agent-os-discover-standards/SKILL.md b/.github/skills/agent-os-discover-standards/SKILL.md deleted file mode 100644 index e741dd60..00000000 --- a/.github/skills/agent-os-discover-standards/SKILL.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -name: agent-os-discover-standards -description: Portable workflow for discovering concise project standards and writing them to agent-os/standards/ for Copilot and Codex sessions without Claude slash-command dependencies. ---- - -# Agent OS Discover Standards - -## Referenced skills - -- `agent-os-index-standards`: on-demand refresh of `agent-os/standards/index.yml` after standard files are added or removed. - -## When to use - -- You need to discover tribal conventions from code and store them as reusable standards. -- The target output is one or more files under `agent-os/standards/`. -- You want a Copilot/Codex-friendly flow with explicit user confirmations. - -## When not to use - -- You only need to rebuild the index; use `agent-os-index-standards`. -- You are implementing code changes rather than documenting standards. -- You need to execute standards, not author or refine them. - -## Workflow - -1. Propose a focused area to inspect (or confirm the area provided by the user). -2. Review representative files and extract only non-obvious, repeated, opinionated patterns. -3. For each candidate standard, ask 1-2 short why/exceptions questions before drafting. -4. Draft one concise standard at a time and request explicit approval before writing. -5. Write approved files to `agent-os/standards//.md`; append to a related existing file instead of creating a duplicate. -6. After finishing one area, offer to discover standards in another area or stop. -7. Refresh the index with `agent-os-index-standards` when file changes are complete. - -## Boundaries - -- Keep standards concise and scannable for AI context windows. -- Do not copy framework defaults unless they are project-specific constraints. -- Do not write files without user confirmation. - -## Validation - -- New standards are located under `agent-os/standards/`. -- Each standard contains one concept with concrete examples when useful. -- `agent-os/standards/index.yml` is updated after additions or deletions. - -## Source command parity - -- Derived from `.claude/commands/agent-os/discover-standards.md`. -- Runtime language is portable for Copilot and Codex and does not rely on Claude slash commands. diff --git a/.github/skills/agent-os-index-standards/SKILL.md b/.github/skills/agent-os-index-standards/SKILL.md deleted file mode 100644 index 8a830fb5..00000000 --- a/.github/skills/agent-os-index-standards/SKILL.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -name: agent-os-index-standards -description: Portable workflow for rebuilding agent-os/standards/index.yml from standards files with deterministic ordering and short descriptions. ---- - -# Agent OS Index Standards - -## Referenced skills - -- None. - -## When to use - -- `agent-os/standards/index.yml` is stale, missing entries, or includes deleted files. -- Standards files were recently added, renamed, or removed. - -## When not to use - -- You need to discover new standards from code; use `agent-os-discover-standards`. -- You need to inject standards into a conversation or plan; use `agent-os-inject-standards`. - -## Workflow - -1. Scan `agent-os/standards/` recursively for `.md` files. -2. Interpret files in `agent-os/standards/` root as the reserved folder key `root`. -3. Load the current `agent-os/standards/index.yml` when present. -4. For each new file, propose a one-sentence description and confirm it before writing. -5. Remove stale index entries for deleted files automatically. -6. Write YAML sorted by folder name and then file name. -7. Report what changed: entries added, removed, and unchanged. - -## Boundaries - -- Keep descriptions to one short sentence. -- Use filenames without `.md` extension in index keys. -- Do not create a physical `root/` folder. - -## Validation - -- Every standard file has an index entry. -- No index entry points to a missing file. -- Ordering is deterministic (alphabetical folders, alphabetical file keys). - -## Source command parity - -- Derived from `.claude/commands/agent-os/index-standards.md`. -- Runtime language is portable for Copilot and Codex and does not rely on Claude slash commands. diff --git a/.github/skills/agent-os-inject-standards/SKILL.md b/.github/skills/agent-os-inject-standards/SKILL.md deleted file mode 100644 index 176d1045..00000000 --- a/.github/skills/agent-os-inject-standards/SKILL.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -name: agent-os-inject-standards -description: Portable workflow for selecting and injecting relevant standards from agent-os/standards/ into implementation, skill-authoring, or planning contexts. ---- - -# Agent OS Inject Standards - -## Referenced skills - -- `agent-os-index-standards`: on-demand repair when `agent-os/standards/index.yml` is missing or stale. - -## When to use - -- You need standards context for code work, planning, or skill authoring. -- You want automatic suggestions from `agent-os/standards/index.yml`. -- You need explicit injection of chosen folders or files. - -## When not to use - -- You need to create new standards from source code; use `agent-os-discover-standards`. -- You need only to refresh index metadata; use `agent-os-index-standards`. - -## Workflow - -1. Determine scenario: conversation, skill authoring, or planning. -2. In auto mode, read `agent-os/standards/index.yml` and propose 2-5 relevant standards. -3. In explicit mode, resolve folder/file targets directly, treating `root` as the reserved key for files directly in `agent-os/standards/`. -4. In explicit mode, if a target is missing, list available standards in that folder and ask for the intended one instead of injecting. -5. Confirm what to include, then inject either file references or full content. -6. In the conversation scenario, surface related repository skills by name for awareness without invoking them. -7. If index is missing or empty, stop and request indexing via `agent-os-index-standards`. - -## Boundaries - -- Do not auto-load unrelated standards. -- Ask for confirmation when scenario is ambiguous. -- Keep output focused and lightweight. -- Surface related skills only; never invoke them automatically. - -## Validation - -- Injected standards exist on disk under `agent-os/standards/`. -- Scenario-specific format is respected (conversation vs. skill vs. plan). -- Suggestions remain narrow and relevant to the active task. - -## Source command parity - -- Derived from `.claude/commands/agent-os/inject-standards.md`. -- Runtime language is portable for Copilot and Codex and does not rely on Claude slash commands. diff --git a/.github/skills/agent-os-plan-product/SKILL.md b/.github/skills/agent-os-plan-product/SKILL.md deleted file mode 100644 index cb746b43..00000000 --- a/.github/skills/agent-os-plan-product/SKILL.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -name: agent-os-plan-product -description: Portable workflow for creating or updating agent-os/product mission, roadmap, and tech-stack documents through lightweight guided questions. ---- - -# Agent OS Plan Product - -## Referenced skills - -- `agent-os-inject-standards`: on-demand lookup of relevant standards, including `agent-os/standards/global/tech-stack.md` when present. - -## When to use - -- Product context docs are missing or outdated in `agent-os/product/`. -- You need a lightweight mission, roadmap, and tech-stack baseline for later planning. - -## When not to use - -- You are shaping a concrete feature spec; use `agent-os-shape-spec`. -- You only need one small edit in product docs without guided discovery. - -## Workflow - -1. Check which files already exist: `mission.md`, `roadmap.md`, `tech-stack.md`. -2. If files exist, ask whether to replace all, update selected files, or cancel. -3. Collect concise inputs for product problem, target users, and differentiator. -4. Collect MVP and post-launch feature priorities. -5. Reuse `agent-os/standards/global/tech-stack.md` when applicable, otherwise collect stack details. -6. Write or update files under `agent-os/product/` with clear sections. - -## Boundaries - -- Do not overwrite existing docs without explicit user confirmation. -- Keep content concise and editable. -- If answers are incomplete, use clear placeholders instead of inventing detail. - -## Validation - -- Target files exist under `agent-os/product/` after approval. -- Content reflects user-provided inputs and selected update mode. -- Tech stack section clearly distinguishes frontend, backend, database, and other tools when relevant. - -## Source command parity - -- Derived from `.claude/commands/agent-os/plan-product.md`. -- Runtime language is portable for Copilot and Codex and does not rely on Claude slash commands. diff --git a/.github/skills/agent-os-shape-spec/SKILL.md b/.github/skills/agent-os-shape-spec/SKILL.md deleted file mode 100644 index 2ccb64bd..00000000 --- a/.github/skills/agent-os-shape-spec/SKILL.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -name: agent-os-shape-spec -description: Portable workflow for shaping significant work into agent-os/specs// with clear scope, references, standards, and execution-ready tasks. ---- - -# Agent OS Shape Spec - -## Referenced skills - -- `agent-os-inject-standards`: on-demand discovery and inclusion of relevant standards during shaping. -- `agent-os-plan-product`: on-demand product-context refresh when `agent-os/product/` context is missing or stale. - -## When to use - -- Significant work needs explicit shaping before implementation. -- You need to save reusable planning artifacts under `agent-os/specs/`. - -## When not to use - -- The request is a small direct edit with clear validation. -- You are not in a planning context and no spec package is needed. - -## Workflow - -1. Confirm planning context and feature scope with short clarification questions. -2. Collect optional visuals and reference implementations. -3. Read product context from `agent-os/product/` when available. -4. Identify relevant standards from `agent-os/standards/index.yml` and confirm inclusion. -5. Create `agent-os/specs/YYYY-MM-DD-HHMM-/`. -6. Build an execution plan where Task 1 is always saving spec documentation. -7. Prepare `plan.md`, `shape.md`, `standards.md`, `references.md`, and `visuals/` as applicable. - -## Boundaries - -- Use explicit user approval language; do not rely on Claude-only plan-mode mechanics. -- Keep shaping lightweight and actionable. -- Do not auto-start implementation from shaping output without approval. - -## Validation - -- Spec folder uses `YYYY-MM-DD-HHMM-` naming under `agent-os/specs/`. -- Task 1 in `plan.md` is "Save spec documentation". -- Supporting files capture scope, decisions, standards, and references relevant to the work. - -## Source command parity - -- Derived from `.claude/commands/agent-os/shape-spec.md`. -- Runtime language is portable for Copilot and Codex and does not rely on Claude slash commands. diff --git a/.github/skills/anthropic-docx/SKILL.md b/.github/skills/anthropic-docx/SKILL.md index 2b1fe9c2..7f4fedb7 100644 --- a/.github/skills/anthropic-docx/SKILL.md +++ b/.github/skills/anthropic-docx/SKILL.md @@ -10,7 +10,7 @@ A `.docx` is a ZIP archive of XML files. Choose your approach by task: | Task | Approach | |---|---| -| **Create** a new document | Write a `anthropic-docx` (npm) script — see gotchas below | +| **Create** a new document | Write a `docx` (npm) script — see gotchas below | | **Edit** an existing document | `unzip` → edit `word/document.xml` → `zip` (docx-js cannot open existing files) | | **Read** content | `pandoc -t markdown file.docx` | @@ -18,7 +18,7 @@ A `.docx` is a ZIP archive of XML files. Choose your approach by task: ## Creating with docx-js — gotchas -`anthropic-docx` is preinstalled — do not run `npm install` first; write the script and `require('docx')` directly. Only if that require fails: `npm install docx`. The model knows the API; these are the footguns: +`docx` is preinstalled — do not run `npm install` first; write the script and `require('docx')` directly. Only if that require fails: `npm install docx`. The model knows the API; these are the footguns: - **Page size defaults to A4.** For US Letter set `page: { size: { width: 12240, height: 15840 } }` (DXA; 1440 = 1″). - **Landscape:** pass portrait dimensions and `orientation: PageOrientation.LANDSCAPE` — docx-js swaps width/height internally. @@ -88,4 +88,4 @@ The script writes `comments.xml`, `commentsExtended.xml`, `commentsIds.xml`, `co ## Dependencies -`anthropic-docx` (npm, preinstalled — install only if `require('docx')` fails) · `pandoc` · LibreOffice (`soffice`) · `pdftoppm` (Poppler) +`docx` (npm, preinstalled — install only if `require('docx')` fails) · `pandoc` · LibreOffice (`soffice`) · `pdftoppm` (Poppler) diff --git a/.github/skills/anthropic-docx/scripts/__init__.py b/.github/skills/anthropic-docx/scripts/__init__.py old mode 100644 new mode 100755 index 8b137891..e5a0d9b4 --- a/.github/skills/anthropic-docx/scripts/__init__.py +++ b/.github/skills/anthropic-docx/scripts/__init__.py @@ -1 +1 @@ - +#!/usr/bin/env python3 diff --git a/.github/skills/anthropic-docx/scripts/accept_changes.py b/.github/skills/anthropic-docx/scripts/accept_changes.py old mode 100644 new mode 100755 index 8e363161..cf5aae7f --- a/.github/skills/anthropic-docx/scripts/accept_changes.py +++ b/.github/skills/anthropic-docx/scripts/accept_changes.py @@ -1,3 +1,4 @@ +#!/usr/bin/env python3 """Accept all tracked changes in a DOCX file using LibreOffice. Requires LibreOffice (soffice) to be installed. diff --git a/.github/skills/anthropic-docx/scripts/comment.py b/.github/skills/anthropic-docx/scripts/comment.py old mode 100644 new mode 100755 index 46ed5f52..45af1209 --- a/.github/skills/anthropic-docx/scripts/comment.py +++ b/.github/skills/anthropic-docx/scripts/comment.py @@ -1,3 +1,4 @@ +#!/usr/bin/env python3 """Add comments to a DOCX document. Accepts either an unpacked directory OR a .docx/.dotx file directly. diff --git a/.github/skills/anthropic-docx/scripts/merge_runs.py b/.github/skills/anthropic-docx/scripts/merge_runs.py old mode 100644 new mode 100755 index 4c7c1bf2..6cc10726 --- a/.github/skills/anthropic-docx/scripts/merge_runs.py +++ b/.github/skills/anthropic-docx/scripts/merge_runs.py @@ -1,3 +1,4 @@ +#!/usr/bin/env python3 """Merge adjacent identically-formatted runs in a DOCX. Word fragments paragraph text across many elements (revision ids, diff --git a/.github/skills/anthropic-docx/scripts/office/validate.py b/.github/skills/anthropic-docx/scripts/office/validate.py old mode 100644 new mode 100755 index 29ca186a..87c0812b --- a/.github/skills/anthropic-docx/scripts/office/validate.py +++ b/.github/skills/anthropic-docx/scripts/office/validate.py @@ -1,3 +1,4 @@ +#!/usr/bin/env python3 """ Command line tool to validate Office document XML files against XSD schemas and tracked changes. diff --git a/.github/skills/anthropic-pdf/SKILL.md b/.github/skills/anthropic-pdf/SKILL.md index 5481d699..5cd70b0d 100644 --- a/.github/skills/anthropic-pdf/SKILL.md +++ b/.github/skills/anthropic-pdf/SKILL.md @@ -1,6 +1,7 @@ --- name: anthropic-pdf -description: "Use when tasks involve reading, creating, or reviewing PDF files where rendering and layout matter; prefer visual checks by rendering pages (Poppler) and use Python tools such as `reportlab`, `pdfplumber`, and `pypdf` for generation and extraction." +description: Use this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill. +license: Proprietary. LICENSE.txt has complete terms --- # PDF Processing Guide @@ -14,9 +15,11 @@ This guide covers essential PDF processing operations using Python libraries and ```python from pypdf import PdfReader, PdfWriter +# Read a PDF reader = PdfReader("document.pdf") print(f"Pages: {len(reader.pages)}") +# Extract text text = "" for page in reader.pages: text += page.extract_text() @@ -62,13 +65,11 @@ print(f"Creator: {meta.creator}") #### Rotate Pages ```python -from pypdf import PdfReader, PdfWriter - reader = PdfReader("input.pdf") writer = PdfWriter() page = reader.pages[0] -page.rotate(90) +page.rotate(90) # Rotate 90 degrees clockwise writer.add_page(page) with open("rotated.pdf", "wb") as output: @@ -107,10 +108,11 @@ with pdfplumber.open("document.pdf") as pdf: for page in pdf.pages: tables = page.extract_tables() for table in tables: - if table: + if table: # Check if table is not empty df = pd.DataFrame(table[1:], columns=table[0]) all_tables.append(df) +# Combine all tables if all_tables: combined_df = pd.concat(all_tables, ignore_index=True) combined_df.to_excel("extracted_tables.xlsx", index=False) @@ -126,10 +128,14 @@ from reportlab.pdfgen import canvas c = canvas.Canvas("hello.pdf", pagesize=letter) width, height = letter +# Add text c.drawString(100, height - 100, "Hello World!") c.drawString(100, height - 120, "This is a PDF created with reportlab") + +# Add a line c.line(100, height - 140, 400, height - 140) +# Save c.save() ``` @@ -143,6 +149,7 @@ doc = SimpleDocTemplate("report.pdf", pagesize=letter) styles = getSampleStyleSheet() story = [] +# Add content title = Paragraph("Report Title", styles['Title']) story.append(title) story.append(Spacer(1, 12)) @@ -151,15 +158,17 @@ body = Paragraph("This is the body of the report. " * 20, styles['Normal']) story.append(body) story.append(PageBreak()) +# Page 2 story.append(Paragraph("Page 2", styles['Heading1'])) story.append(Paragraph("Content for page 2", styles['Normal'])) +# Build PDF doc.build(story) ``` #### Subscripts and Superscripts -**IMPORTANT**: Never use Unicode subscript/superscript characters in ReportLab PDFs. The built-in fonts do not include these glyphs, causing them to render as solid black boxes. +**IMPORTANT**: Never use Unicode subscript/superscript characters (₀₁₂₃₄₅₆₇₈₉, ⁰¹²³⁴⁵⁶⁷⁸⁹) in ReportLab PDFs. The built-in fonts do not include these glyphs, causing them to render as solid black boxes. Instead, use ReportLab's XML markup tags in Paragraph objects: ```python @@ -168,32 +177,54 @@ from reportlab.lib.styles import getSampleStyleSheet styles = getSampleStyleSheet() +# Subscripts: use tag chemical = Paragraph("H2O", styles['Normal']) + +# Superscripts: use tag squared = Paragraph("x2 + y2", styles['Normal']) ``` +For canvas-drawn text (not Paragraph objects), manually adjust font the size and position rather than using Unicode subscripts/superscripts. + ## Command-Line Tools ### pdftotext (poppler-utils) ```bash +# Extract text pdftotext input.pdf output.txt + +# Extract text preserving layout pdftotext -layout input.pdf output.txt -pdftotext -f 1 -l 5 input.pdf output.txt + +# Extract specific pages +pdftotext -f 1 -l 5 input.pdf output.txt # Pages 1-5 ``` ### qpdf ```bash +# Merge PDFs qpdf --empty --pages file1.pdf file2.pdf -- merged.pdf + +# Split pages qpdf input.pdf --pages . 1-5 -- pages1-5.pdf qpdf input.pdf --pages . 6-10 -- pages6-10.pdf -qpdf input.pdf output.pdf --rotate=+90:1 + +# Rotate pages +qpdf input.pdf output.pdf --rotate=+90:1 # Rotate page 1 by 90 degrees + +# Remove password qpdf --password=mypassword --decrypt encrypted.pdf decrypted.pdf ``` ### pdftk (if available) ```bash +# Merge pdftk file1.pdf file2.pdf cat output merged.pdf + +# Split pdftk input.pdf burst + +# Rotate pdftk input.pdf rotate 1east output rotated.pdf ``` @@ -201,11 +232,14 @@ pdftk input.pdf rotate 1east output rotated.pdf ### Extract Text from Scanned PDFs ```python +# Requires: pip install pytesseract pdf2image import pytesseract from pdf2image import convert_from_path +# Convert PDF to images images = convert_from_path('scanned.pdf') +# OCR each page text = "" for i, image in enumerate(images): text += f"Page {i+1}:\n" @@ -219,8 +253,10 @@ print(text) ```python from pypdf import PdfReader, PdfWriter +# Create watermark (or load existing) watermark = PdfReader("watermark.pdf").pages[0] +# Apply to all pages reader = PdfReader("document.pdf") writer = PdfWriter() @@ -234,7 +270,10 @@ with open("watermarked.pdf", "wb") as output: ### Extract Images ```bash +# Using pdfimages (poppler-utils) pdfimages -j input.pdf output_prefix + +# This extracts all images as output_prefix-000.jpg, output_prefix-001.jpg, etc. ``` ### Password Protection @@ -247,6 +286,7 @@ writer = PdfWriter() for page in reader.pages: writer.add_page(page) +# Add password writer.encrypt("userpassword", "ownerpassword") with open("encrypted.pdf", "wb") as output: diff --git a/.github/skills/anthropic-pdf/forms.md b/.github/skills/anthropic-pdf/forms.md index 5f634ab9..6e7e1e0d 100644 --- a/.github/skills/anthropic-pdf/forms.md +++ b/.github/skills/anthropic-pdf/forms.md @@ -14,6 +14,7 @@ If the PDF has fillable form fields: "rect": ([left, bottom, right, top] bounding box in PDF coordinates, y=0 is the bottom of the page), "type": ("text", "checkbox", "radio_group", or "choice"), }, + // Checkboxes have "checked_value" and "unchecked_value" properties: { "field_id": (unique ID for the field), "page": (page number, 1-based), @@ -21,6 +22,7 @@ If the PDF has fillable form fields: "checked_value": (Set the field to this value to check the checkbox), "unchecked_value": (Set the field to this value to uncheck the checkbox), }, + // Radio groups have a "radio_options" list with the possible choices. { "field_id": (unique ID for the field), "page": (page number, 1-based), @@ -30,8 +32,10 @@ If the PDF has fillable form fields: "value": (set the field to this value to select this radio option), "rect": (bounding box for the radio button for this option) }, + // Other radio options ] }, + // Multiple choice fields have a "choice_options" list with the possible choices: { "field_id": (unique ID for the field), "page": (page number, 1-based), @@ -41,6 +45,7 @@ If the PDF has fillable form fields: "value": (set the field to this value to select this option), "text": (display text of the option) }, + // Other choice options ], } ] @@ -52,17 +57,18 @@ Then analyze the images to determine the purpose of each form field (make sure t ``` [ { - "field_id": "last_name", + "field_id": "last_name", // Must match the field_id from `extract_form_field_info.py` "description": "The user's last name", - "page": 1, + "page": 1, // Must match the "page" value in field_info.json "value": "Simpson" }, { "field_id": "Checkbox12", "description": "Checkbox to be checked if the user is 18 or over", "page": 1, - "value": "/On" + "value": "/On" // If this is a checkbox, use its "checked_value" value to check it. If it's a radio button group, use one of the "value" values in "radio_options". }, + // more fields ] ``` - Run the `fill_fillable_fields.py` script from this file's directory to create a filled-in PDF: diff --git a/.github/skills/anthropic-pdf/reference.md b/.github/skills/anthropic-pdf/reference.md index 3012f4d1..bd4cd7ae 100644 --- a/.github/skills/anthropic-pdf/reference.md +++ b/.github/skills/anthropic-pdf/reference.md @@ -12,17 +12,21 @@ pypdfium2 is a Python binding for PDFium (Chromium's PDF library). It's excellen import pypdfium2 as pdfium from PIL import Image +# Load PDF pdf = pdfium.PdfDocument("document.pdf") -page = pdf[0] +# Render page to image +page = pdf[0] # First page bitmap = page.render( - scale=2.0, - rotation=0 + scale=2.0, # Higher resolution + rotation=0 # No rotation ) +# Convert to PIL Image img = bitmap.to_pil() img.save("page_1.png", "PNG") +# Process multiple pages for i, page in enumerate(pdf): bitmap = page.render(scale=1.5) img = bitmap.to_pil() @@ -51,12 +55,15 @@ import { PDFDocument } from 'pdf-lib'; import fs from 'fs'; async function manipulatePDF() { + // Load existing PDF const existingPdfBytes = fs.readFileSync('input.pdf'); const pdfDoc = await PDFDocument.load(existingPdfBytes); + // Get page count const pageCount = pdfDoc.getPageCount(); console.log(`Document has ${pageCount} pages`); + // Add new page const newPage = pdfDoc.addPage([600, 400]); newPage.drawText('Added by pdf-lib', { x: 100, @@ -64,6 +71,7 @@ async function manipulatePDF() { size: 16 }); + // Save modified PDF const pdfBytes = await pdfDoc.save(); fs.writeFileSync('modified.pdf', pdfBytes); } @@ -77,12 +85,15 @@ import fs from 'fs'; async function createPDF() { const pdfDoc = await PDFDocument.create(); + // Add fonts const helveticaFont = await pdfDoc.embedFont(StandardFonts.Helvetica); const helveticaBold = await pdfDoc.embedFont(StandardFonts.HelveticaBold); - const page = pdfDoc.addPage([595, 842]); + // Add page + const page = pdfDoc.addPage([595, 842]); // A4 size const { width, height } = page.getSize(); + // Add text with styling page.drawText('Invoice #12345', { x: 50, y: height - 50, @@ -91,6 +102,7 @@ async function createPDF() { color: rgb(0.2, 0.2, 0.8) }); + // Add rectangle (header background) page.drawRectangle({ x: 40, y: height - 100, @@ -99,6 +111,7 @@ async function createPDF() { color: rgb(0.9, 0.9, 0.9) }); + // Add table-like content const items = [ ['Item', 'Qty', 'Price', 'Total'], ['Widget', '2', '$50', '$100'], @@ -131,17 +144,21 @@ import { PDFDocument } from 'pdf-lib'; import fs from 'fs'; async function mergePDFs() { + // Create new document const mergedPdf = await PDFDocument.create(); + // Load source PDFs const pdf1Bytes = fs.readFileSync('doc1.pdf'); const pdf2Bytes = fs.readFileSync('doc2.pdf'); const pdf1 = await PDFDocument.load(pdf1Bytes); const pdf2 = await PDFDocument.load(pdf2Bytes); + // Copy pages from first PDF const pdf1Pages = await mergedPdf.copyPages(pdf1, pdf1.getPageIndices()); pdf1Pages.forEach(page => mergedPdf.addPage(page)); + // Copy specific pages from second PDF (pages 0, 2, 4) const pdf2Pages = await mergedPdf.copyPages(pdf2, [0, 2, 4]); pdf2Pages.forEach(page => mergedPdf.addPage(page)); @@ -158,17 +175,21 @@ PDF.js is Mozilla's JavaScript library for rendering PDFs in the browser. ```javascript import * as pdfjsLib from 'pdfjs-dist'; -pdfjsLib.GlobalWorkerOptions.workerSrc = './pdf.worker.js'; +// Configure worker (important for performance) +pdfjsLib.GlobalWorkerOptions.workerSrc = './anthropic-pdf.worker.js'; async function renderPDF() { + // Load PDF const loadingTask = pdfjsLib.getDocument('document.pdf'); const pdf = await loadingTask.promise; console.log(`Loaded PDF with ${pdf.numPages} pages`); + // Get first page const page = await pdf.getPage(1); const viewport = page.getViewport({ scale: 1.5 }); + // Render to canvas const canvas = document.createElement('canvas'); const context = canvas.getContext('2d'); canvas.height = viewport.height; @@ -194,6 +215,7 @@ async function extractText() { let fullText = ''; + // Extract text from all pages for (let i = 1; i <= pdf.numPages; i++) { const page = await pdf.getPage(i); const textContent = await page.getTextContent(); @@ -204,6 +226,7 @@ async function extractText() { fullText += `\n--- Page ${i} ---\n${pageText}`; + // Get text with coordinates for advanced processing const textWithCoords = textContent.items.map(item => ({ text: item.str, x: item.transform[4], @@ -245,20 +268,33 @@ async function extractAnnotations() { #### Extract Text with Bounding Box Coordinates ```bash +# Extract text with bounding box coordinates (essential for structured data) pdftotext -bbox-layout document.pdf output.xml + +# The XML output contains precise coordinates for each text element ``` #### Advanced Image Conversion ```bash +# Convert to PNG images with specific resolution pdftoppm -png -r 300 document.pdf output_prefix + +# Convert specific page range with high resolution pdftoppm -png -r 600 -f 1 -l 3 document.pdf high_res_pages + +# Convert to JPEG with quality setting pdftoppm -jpeg -jpegopt quality=85 -r 200 document.pdf jpeg_output ``` #### Extract Embedded Images ```bash +# Extract all embedded images with metadata pdfimages -j -p document.pdf page_images + +# List image info without extracting pdfimages -list document.pdf + +# Extract images in their original format pdfimages -all document.pdf images/img ``` @@ -266,24 +302,41 @@ pdfimages -all document.pdf images/img #### Complex Page Manipulation ```bash +# Split PDF into groups of pages qpdf --split-pages=3 input.pdf output_group_%02d.pdf + +# Extract specific pages with complex ranges qpdf input.pdf --pages input.pdf 1,3-5,8,10-end -- extracted.pdf + +# Merge specific pages from multiple PDFs qpdf --empty --pages doc1.pdf 1-3 doc2.pdf 5-7 doc3.pdf 2,4 -- combined.pdf ``` #### PDF Optimization and Repair ```bash +# Optimize PDF for web (linearize for streaming) qpdf --linearize input.pdf optimized.pdf + +# Remove unused objects and compress qpdf --optimize-level=all input.pdf compressed.pdf + +# Attempt to repair corrupted PDF structure qpdf --check input.pdf qpdf --fix-qdf damaged.pdf repaired.pdf + +# Show detailed PDF structure for debugging qpdf --show-all-pages input.pdf > structure.txt ``` #### Advanced Encryption ```bash +# Add password protection with specific permissions qpdf --encrypt user_pass owner_pass 256 --print=none --modify=none -- input.pdf encrypted.pdf + +# Check encryption status qpdf --show-encryption encrypted.pdf + +# Remove password protection (requires password) qpdf --password=secret123 --decrypt encrypted.pdf decrypted.pdf ``` @@ -298,10 +351,12 @@ import pdfplumber with pdfplumber.open("document.pdf") as pdf: page = pdf.pages[0] + # Extract all text with coordinates chars = page.chars - for char in chars[:10]: + for char in chars[:10]: # First 10 characters print(f"Char: '{char['text']}' at x:{char['x0']:.1f} y:{char['y0']:.1f}") + # Extract text by bounding box (left, top, right, bottom) bbox_text = page.within_bbox((100, 100, 400, 200)).extract_text() ``` @@ -313,6 +368,7 @@ import pandas as pd with pdfplumber.open("complex_table.pdf") as pdf: page = pdf.pages[0] + # Extract tables with custom settings for complex layouts table_settings = { "vertical_strategy": "lines", "horizontal_strategy": "lines", @@ -321,6 +377,7 @@ with pdfplumber.open("complex_table.pdf") as pdf: } tables = page.extract_tables(table_settings) + # Visual debugging for table extraction img = page.to_image(resolution=150) img.save("debug_layout.png") ``` @@ -333,19 +390,23 @@ from reportlab.platypus import SimpleDocTemplate, Table, TableStyle, Paragraph from reportlab.lib.styles import getSampleStyleSheet from reportlab.lib import colors +# Sample data data = [ ['Product', 'Q1', 'Q2', 'Q3', 'Q4'], ['Widgets', '120', '135', '142', '158'], ['Gadgets', '85', '92', '98', '105'] ] +# Create PDF with table doc = SimpleDocTemplate("report.pdf") elements = [] +# Add title styles = getSampleStyleSheet() title = Paragraph("Quarterly Sales Report", styles['Title']) elements.append(title) +# Add table with advanced styling table = Table(data) table.setStyle(TableStyle([ ('BACKGROUND', (0, 0), (-1, 0), colors.grey), @@ -368,6 +429,7 @@ doc.build(elements) #### Method 1: Using pdfimages (fastest) ```bash +# Extract all images with original quality pdfimages -all document.pdf images/img ``` @@ -381,12 +443,21 @@ def extract_figures(pdf_path, output_dir): pdf = pdfium.PdfDocument(pdf_path) for page_num, page in enumerate(pdf): + # Render high-resolution page bitmap = page.render(scale=3.0) img = bitmap.to_pil() + # Convert to numpy for processing img_array = np.array(img) + # Simple figure detection (non-white regions) mask = np.any(img_array != [255, 255, 255], axis=2) + + # Find contours and extract bounding boxes + # (This is simplified - real implementation would need more sophisticated detection) + + # Save detected figures + # ... implementation depends on specific needs ``` ### Batch PDF Processing with Error Handling @@ -442,6 +513,7 @@ from pypdf import PdfWriter, PdfReader reader = PdfReader("input.pdf") writer = PdfWriter() +# Crop page (left, bottom, right, top in points) page = reader.pages[0] page.mediabox.left = 50 page.mediabox.bottom = 50 @@ -475,6 +547,7 @@ with open("cropped.pdf", "wb") as output: ### 5. Memory Management ```python +# Process PDFs in chunks def process_large_pdf(pdf_path, chunk_size=10): reader = PdfReader(pdf_path) total_pages = len(reader.pages) @@ -486,6 +559,7 @@ def process_large_pdf(pdf_path, chunk_size=10): for i in range(start_idx, end_idx): writer.add_page(reader.pages[i]) + # Process chunk with open(f"chunk_{start_idx//chunk_size}.pdf", "wb") as output: writer.write(output) ``` @@ -494,6 +568,7 @@ def process_large_pdf(pdf_path, chunk_size=10): ### Encrypted PDFs ```python +# Handle password-protected PDFs from pypdf import PdfReader try: @@ -506,12 +581,14 @@ except Exception as e: ### Corrupted PDFs ```bash +# Use qpdf to repair qpdf --check corrupted.pdf qpdf --replace-input corrupted.pdf ``` ### Text Extraction Issues ```python +# Fallback to OCR for scanned PDFs import pytesseract from pdf2image import convert_from_path @@ -532,4 +609,4 @@ def extract_text_with_ocr(pdf_path): - **poppler-utils**: GPL-2 License - **qpdf**: Apache License - **pdf-lib**: MIT License -- **pdfjs-dist**: Apache License +- **pdfjs-dist**: Apache License \ No newline at end of file diff --git a/.github/skills/anthropic-pdf/scripts/extract_form_structure.py b/.github/skills/anthropic-pdf/scripts/extract_form_structure.py old mode 100644 new mode 100755 index f219e7d5..217c5a9f --- a/.github/skills/anthropic-pdf/scripts/extract_form_structure.py +++ b/.github/skills/anthropic-pdf/scripts/extract_form_structure.py @@ -1,3 +1,4 @@ +#!/usr/bin/env python3 """ Extract form structure from a non-fillable PDF. diff --git a/.github/skills/anthropic-pptx/scripts/add_slide.py b/.github/skills/anthropic-pptx/scripts/add_slide.py old mode 100644 new mode 100755 index f013ea94..727b3a7f --- a/.github/skills/anthropic-pptx/scripts/add_slide.py +++ b/.github/skills/anthropic-pptx/scripts/add_slide.py @@ -1,3 +1,4 @@ +#!/usr/bin/env python3 """Add a slide to a PPTX: duplicate an existing slide or instantiate a layout. Does all of the package bookkeeping, so the deck stays valid: diff --git a/.github/skills/anthropic-pptx/scripts/clean.py b/.github/skills/anthropic-pptx/scripts/clean.py old mode 100644 new mode 100755 index 551dd231..37dbc00f --- a/.github/skills/anthropic-pptx/scripts/clean.py +++ b/.github/skills/anthropic-pptx/scripts/clean.py @@ -1,3 +1,4 @@ +#!/usr/bin/env python3 """Remove unreferenced files from an unpacked PPTX directory. Usage: python clean.py diff --git a/.github/skills/anthropic-pptx/scripts/office/validate.py b/.github/skills/anthropic-pptx/scripts/office/validate.py old mode 100644 new mode 100755 index 29ca186a..87c0812b --- a/.github/skills/anthropic-pptx/scripts/office/validate.py +++ b/.github/skills/anthropic-pptx/scripts/office/validate.py @@ -1,3 +1,4 @@ +#!/usr/bin/env python3 """ Command line tool to validate Office document XML files against XSD schemas and tracked changes. diff --git a/.github/skills/anthropic-pptx/scripts/thumbnail.py b/.github/skills/anthropic-pptx/scripts/thumbnail.py old mode 100644 new mode 100755 index d49cac0e..30a299bc --- a/.github/skills/anthropic-pptx/scripts/thumbnail.py +++ b/.github/skills/anthropic-pptx/scripts/thumbnail.py @@ -1,3 +1,4 @@ +#!/usr/bin/env python3 """Create thumbnail grids from PowerPoint presentation slides. Creates a grid layout of slide thumbnails for quick visual analysis. diff --git a/.github/skills/anthropic-xlsx/scripts/office/validate.py b/.github/skills/anthropic-xlsx/scripts/office/validate.py old mode 100644 new mode 100755 index 29ca186a..87c0812b --- a/.github/skills/anthropic-xlsx/scripts/office/validate.py +++ b/.github/skills/anthropic-xlsx/scripts/office/validate.py @@ -1,3 +1,4 @@ +#!/usr/bin/env python3 """ Command line tool to validate Office document XML files against XSD schemas and tracked changes. diff --git a/.github/skills/anthropic-xlsx/scripts/recalc.py b/.github/skills/anthropic-xlsx/scripts/recalc.py old mode 100644 new mode 100755 index 6232be2d..ea1a129d --- a/.github/skills/anthropic-xlsx/scripts/recalc.py +++ b/.github/skills/anthropic-xlsx/scripts/recalc.py @@ -1,3 +1,4 @@ +#!/usr/bin/env python3 """ Excel Formula Recalculation Script Recalculates all formulas in an Excel file using LibreOffice diff --git a/.github/skills/internal-agent-creator/agents/openai.yaml b/.github/skills/internal-agent-creator/agents/openai.yaml index 947c65fe..d2d5169b 100644 --- a/.github/skills/internal-agent-creator/agents/openai.yaml +++ b/.github/skills/internal-agent-creator/agents/openai.yaml @@ -1,4 +1,4 @@ interface: - display_name: "Agent Development" + display_name: "Agent Creator" short_description: "Create, refine, or realign repository-owned Copilot agents" default_prompt: "Use $internal-agent-creator to create or update an internal agent in .github/agents/ following the repository contract." diff --git a/.github/skills/internal-agent-creator/references/subagent-patterns.md b/.github/skills/internal-agent-creator/references/subagent-patterns.md index d1970b4e..bbdb09e1 100644 --- a/.github/skills/internal-agent-creator/references/subagent-patterns.md +++ b/.github/skills/internal-agent-creator/references/subagent-patterns.md @@ -73,7 +73,7 @@ Focused instructions for domain A work. ### Router with explicit dispatch targets ```yaml -agents: ['internal-gateway-idea', 'internal-gateway-review-generic', 'internal-gateway-critical-master', 'internal-gateway-simple-task'] +agents: ['internal-worker-a', 'internal-worker-b', 'internal-worker-c', 'internal-worker-d'] ``` Only these four agents can be invoked as subagents. The platform enforces this. @@ -117,7 +117,7 @@ Handoffs create guided sequential workflows with user-visible buttons between ag ```yaml handoffs: - label: Start Implementation - agent: internal-gateway-review-generic + agent: internal-worker-b prompt: Implement the plan outlined above. send: false ``` diff --git a/.github/skills/internal-agent-support-lane-change-engine/SKILL.md b/.github/skills/internal-agent-support-lane-change-engine/SKILL.md deleted file mode 100644 index ef339910..00000000 --- a/.github/skills/internal-agent-support-lane-change-engine/SKILL.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -name: internal-agent-support-lane-change-engine -description: Use when a repository-owned internal agent needs a consistent user-visible lane-change response after the selected lane no longer fits. ---- - -# Internal Agent Support Lane Change Engine - -## Referenced skills - -- `internal-gateway-simple-task`: source or target lane for concrete local follow-up work. -- `internal-gateway-idea`: source lane when planning or scope definition is needed; target lane when planning or scope definition dominates. -- `internal-gateway-critical-master`: source lane when assumption pressure-testing dominates; target lane when assumption pressure-testing dominates. -- `internal-gateway-execute-plans`: target lane when approved retained-plan execution is the next step. - -Use this skill as the shared lane-mismatch engine for repository-owned internal -agents. - -## When to use - -- A repository-owned internal agent no longer fits the real work. -- The current owner must stop and recommend one better visible owner. - -## Goals - -- Stop before doing off-lane work. -- Explain the concrete mismatch. -- Recommend exactly one better owner when the next lane is clear. -- Fail safe to `internal-gateway-idea` when the next lane is still ambiguous. - -## Recommendation Matrix - -| Current agent | When the boundary breaks | Recommend | -| --- | --- | --- | -| `internal-gateway-simple-task` | Planning or governance becomes dominant | `internal-gateway-idea` | -| `internal-gateway-simple-task` | Assumption pressure-testing becomes dominant | `internal-gateway-critical-master` | -| `internal-gateway-critical-master` | The next step is planning | `internal-gateway-idea` | -| `internal-gateway-idea` | An approved retained plan is ready for execution | `internal-gateway-execute-plans` | diff --git a/.github/skills/internal-agent-support-lane-change-engine/agents/openai.yaml b/.github/skills/internal-agent-support-lane-change-engine/agents/openai.yaml deleted file mode 100644 index 58c481d5..00000000 --- a/.github/skills/internal-agent-support-lane-change-engine/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Internal Agent Support Lane Change Engine" - short_description: "Shared user-visible lane-change guidance" - default_prompt: "Use $internal-agent-support-lane-change-engine when a repository-owned internal agent needs the shared stop-and-recommend lane-change workflow." diff --git a/.github/skills/internal-agent-support-next-step/SKILL.md b/.github/skills/internal-agent-support-next-step/SKILL.md deleted file mode 100644 index f7847541..00000000 --- a/.github/skills/internal-agent-support-next-step/SKILL.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -name: internal-agent-support-next-step -description: Use when a repository-owned agent or prompt needs to package an already-chosen next owner, scope, action, validation path, and risk note for a user-visible transition. ---- - -# Internal Agent Support Next Step - -## Referenced skills - -- `internal-gateway-idea`: source lane that may need a visible next-step transition. -- `internal-gateway-simple-task`: source lane that may need a visible next-step transition. -- `internal-gateway-execute-plans`: source lane that may need a visible next-step transition. -- `internal-gateway-critical-master`: source lane that may need a visible next-step transition. - -Use this skill to format the next step after the next owner has already been -chosen or confirmed. - -## When to use - -- `internal-gateway-idea`, `internal-gateway-simple-task`, - `internal-gateway-execute-plans`, or `internal-gateway-critical-master` - stop with a visible transition. - -## Package Contract - -- `Owner` -- `Scope` -- `Action` -- `Validation` -- `Risk` -- `Continuation` -- `User action required` when `Continuation` is `waiting` diff --git a/.github/skills/internal-agent-support-next-step/agents/openai.yaml b/.github/skills/internal-agent-support-next-step/agents/openai.yaml deleted file mode 100644 index 65c63013..00000000 --- a/.github/skills/internal-agent-support-next-step/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Internal Agent Support Next Step" - short_description: "Package user-visible next actions" - default_prompt: "Use $internal-agent-support-next-step to package the selected next owner, scope, action, validation path, and risk note for a user-visible transition." diff --git a/.github/skills/internal-agent-support-next-step/references/decision-brief.md b/.github/skills/internal-agent-support-next-step/references/decision-brief.md deleted file mode 100644 index 62f350c8..00000000 --- a/.github/skills/internal-agent-support-next-step/references/decision-brief.md +++ /dev/null @@ -1,42 +0,0 @@ -# Decision Brief - -Use this template when a plan phase or next-step package needs a compact bridge -to execution, review, or critical challenge. The brief is a projection of the -decision, not a second canonical plan. - -## Source Pattern - -- Comparative source: `tmp/external-comparison/compound-engineering-plugin/plugins/compound-engineering/skills/ce-plan/references/plan-handoff.md`. -- Adopt the handoff shape only. Do not import the external runtime. - -## Required Fields - -| Field | Required content | -| --- | --- | -| Target state | The smallest complete outcome the next owner should deliver. | -| Anti-scope | Work the next owner must not add silently. | -| Suggested owner | Exact skill or agent owner already selected. | -| Evidence source | Plan path, request, diff, validator output, or reference that justifies the step. | -| Validation path | Command, review path, validator, or explicit validation gap. | -| Known risks | Residual risk, tradeoff, rollback note, or missing evidence. | -| Stop conditions | Conditions that must stop execution or trigger lane change. | - -## Template - -```text -Decision Brief -Target state: -Anti-scope: -Suggested owner: -Evidence source: -Validation path: -Known risks: -Stop conditions: -``` - -## Missing Field Handling - -- If a required field is missing before execution, state the gap visibly. -- If the gap is recoverable from repository files, inspect those files first. -- If the gap cannot be recovered safely, stop and ask for the missing decision. -- Do not fill missing owner, validation, or stop-condition fields from memory. diff --git a/.github/skills/internal-bash-script/SKILL.md b/.github/skills/internal-bash-script/SKILL.md index 7a8aeab3..28dcb762 100644 --- a/.github/skills/internal-bash-script/SKILL.md +++ b/.github/skills/internal-bash-script/SKILL.md @@ -1,6 +1,6 @@ --- name: internal-bash-script -description: Use when creating or modifying standalone Bash scripts or shell utilities with operator-facing behavior, rather than Bash embedded inside composite actions or CI workflows. +description: Use when creating, modifying, or reviewing standalone Bash scripts, utilities, wrappers, launchers, or other operator-facing shell entrypoints. --- # Bash Script Skill @@ -14,11 +14,16 @@ description: Use when creating or modifying standalone Bash scripts or shell uti - New Bash scripts. - Existing Bash scripts that need updates. +- Standalone operator-facing wrappers, launchers, and shell utilities. ## When not to use - Bash embedded in GitHub composite actions; use `internal-github-action-composite`. - GitHub workflow-level behavior; use `internal-github-actions`. +- embedded shell and non-operator Bash helpers; use `internal-bash`. + +Use this skill directly when standalone operator behavior is the primary +contract; the lightweight sibling is not a required preload. ## Compact Bash baseline @@ -34,12 +39,20 @@ description: Use when creating or modifying standalone Bash scripts or shell uti - Prefer `printf` for formatted output and arrays for dynamic commands. - Destructive or repeatable scripts should be idempotent and expose `--dry-run` when operator risk is non-trivial. -- Validate required external commands with `command -v` before first use. - Keep operator entrypoints thin and extract repeated branches into sourced helper files only when reuse is real. - Treat 300 lines as a review threshold and 400 lines as a split-or-justify gate for standalone scripts. - When script output can grow and the script is agent-facing, prefer bounded summaries by default and add an explicit compact or quiet mode that still preserves blockers, failures, and required next actions. - Keep full-detail output reachable through an explicit flag or durable artifact path when operators need full diagnostics. -- Do not add unit tests unless explicitly requested. + +## Testing + +- For behavior changes, create the failing focused check before the first implementation edit. +- Prefer the repository's existing Bash harness. Cover parser decisions, + guards, dry-run behavior, command construction, and rerun safety at their + stable boundary. +- When no harness can exercise the behavior before editing, record a pre-code testability exception and the alternate validation path. Use syntax, lint, + and a safe non-mutating invocation as evidence; do not represent later + regression coverage as test-first work. ## Templates and hardening helpers diff --git a/.github/skills/internal-bash-script/agents/openai.yaml b/.github/skills/internal-bash-script/agents/openai.yaml index cab58853..95a058cf 100644 --- a/.github/skills/internal-bash-script/agents/openai.yaml +++ b/.github/skills/internal-bash-script/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Internal Script Bash" - short_description: "Help with Internal Script Bash tasks" - default_prompt: "Use $internal-bash-script for this task and follow the repository-owned workflow in the skill." + short_description: "Standalone operator-facing Bash" + default_prompt: "Use $internal-bash-script for standalone Bash scripts, utilities, wrappers, launchers, and other operator-facing shell entrypoints; route embedded shell and non-operator Bash helpers to $internal-bash." diff --git a/.github/skills/internal-bash-script/references/templates.md b/.github/skills/internal-bash-script/references/templates.md index e5f28977..3430d141 100644 --- a/.github/skills/internal-bash-script/references/templates.md +++ b/.github/skills/internal-bash-script/references/templates.md @@ -17,17 +17,24 @@ set -euo pipefail DEFAULT_TARGET="default-target" -log_info() { echo "ℹ️ $*"; } -log_warn() { echo "⚠️ $*"; } -log_success() { echo "✅ $*"; } -log_error() { echo "❌ $*" >&2; } +log_info() { printf 'ℹ️ %s\n' "$*"; } +log_warn() { printf '⚠️ %s\n' "$*"; } +log_success() { printf '✅ %s\n' "$*"; } +log_error() { printf '❌ %s\n' "$*" >&2; } main() { local target="$DEFAULT_TARGET" while [[ $# -gt 0 ]]; do case "$1" in - --target) target="${2:?❌ --target requires a value}"; shift 2 ;; + --target) + [[ $# -ge 2 && "$2" != -* ]] || { + log_error "--target requires a value" + exit 1 + } + target="$2" + shift 2 + ;; --help) usage; exit 0 ;; *) log_error "Unknown option: $1"; usage; exit 1 ;; esac @@ -53,10 +60,18 @@ main "$@" ```bash DEFAULT_SCOPE="repo" SCOPE="$DEFAULT_SCOPE" +DRY_RUN=false while [[ $# -gt 0 ]]; do case "$1" in - --scope) SCOPE="${2:?❌ --scope requires a value}"; shift 2 ;; + --scope) + [[ $# -ge 2 && "$2" != -* ]] || { + log_error "--scope requires a value" + exit 1 + } + SCOPE="$2" + shift 2 + ;; --dry-run) DRY_RUN=true; shift ;; --help) usage; exit 0 ;; *) log_error "Unknown option: $1"; usage; exit 1 ;; diff --git a/.github/skills/internal-bash/SKILL.md b/.github/skills/internal-bash/SKILL.md index e4c9e0ed..6cd344e4 100644 --- a/.github/skills/internal-bash/SKILL.md +++ b/.github/skills/internal-bash/SKILL.md @@ -1,6 +1,6 @@ --- name: internal-bash -description: Use when editing shell or Bash files that need lightweight safety, quoting, parser, or validation guidance. +description: Use when embedded shell, Bash snippets, or non-operator Bash helpers need lightweight safety, quoting, parser, or validation guidance before standalone script design is required. --- # Internal Bash @@ -19,8 +19,9 @@ safety to standalone script behavior. ## When to use -- `.sh` files and Bash snippets where the main need is a shared safety baseline. +- Sourced `.sh` helpers and Bash snippets where the main need is a shared safety baseline. - Shell embedded in repository automation when no narrower owner has stronger rules. +- Non-operator Bash helpers that do not own a standalone operator entrypoint. - Quick checks for quoting, strict mode, guard clauses, temp files, and parser choices. ## When not to use @@ -29,6 +30,9 @@ safety to standalone script behavior. - Bash embedded in GitHub composite actions; use `internal-github-action-composite`. - GitHub workflow-level behavior; use `internal-github-actions`. +When a helper becomes a standalone operator-facing script, route to +`internal-bash-script`; this baseline does not remain a required preload. + ## Baseline - Prefer `#!/usr/bin/env bash` for repository-owned Bash scripts. diff --git a/.github/skills/internal-bash/agents/openai.yaml b/.github/skills/internal-bash/agents/openai.yaml index c95dfed9..b8d6a44d 100644 --- a/.github/skills/internal-bash/agents/openai.yaml +++ b/.github/skills/internal-bash/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Internal Bash" - short_description: "Shell safety and Bash routing" - default_prompt: "Use $internal-bash for shell or Bash safety, quoting, parser, and validation guidance." + short_description: "Bash safety and lightweight routing" + default_prompt: "Use $internal-bash for embedded shell, Bash snippets, or non-operator Bash helpers that need lightweight safety, quoting, parser, or validation guidance before standalone script design." diff --git a/.github/skills/internal-bash/references/review-anti-patterns.md b/.github/skills/internal-bash/references/review-anti-patterns.md index cb5fb64f..e1e94f6c 100644 --- a/.github/skills/internal-bash/references/review-anti-patterns.md +++ b/.github/skills/internal-bash/references/review-anti-patterns.md @@ -14,21 +14,21 @@ Baseline owner: `internal-bash` | ID | Anti-pattern | Why | | --- | --- | --- | -| SH-M01 | Missing `set -euo pipefail` | Silent failures and undefined variables | +| SH-M01 | Strict mode omitted without a documented compatibility reason or equivalent error handling | Unchecked failures and undefined variables can silently corrupt behavior | | SH-M02 | Unquoted variable expansion outside `[[ ]]` | Word splitting and globbing bugs | | SH-M03 | `cd` without error handling (`cd dir \|\| exit 1`) | Silent directory change failure | | SH-M04 | Missing `local` keyword for function variables | Pollutes global scope | -| SH-M05 | POSIX `#!/bin/sh` instead of `#!/usr/bin/env bash` | Repo mandates Bash | +| SH-M05 | Bash-specific syntax under a POSIX shell shebang | The declared interpreter cannot reliably execute the script | | SH-M06 | Missing cleanup trap (`trap cleanup EXIT`) for temp files | Resource leak | -| SH-M07 | Function body longer than 30 lines | Complexity concern | +| SH-M07 | Function mixes parsing, orchestration, and mutation | Coupled responsibilities make failure handling and safe testing difficult | ## Minor | ID | Anti-pattern | Why | | --- | --- | --- | -| SH-m01 | `echo` for status messages instead of emoji logs (`ℹ️ ✅ ⚠️ ❌`) | Repo convention violation | +| SH-m01 | `echo` used where portable formatting or escape handling matters | Output can vary between shells and inputs | | SH-m02 | Hardcoded paths (e.g., `/usr/local/bin/tool`) | Portability concern | -| SH-m03 | Missing purpose header comment | Repo convention | +| SH-m03 | Operator-facing script lacks purpose or usage context | Operators cannot discover the entrypoint contract locally | | SH-m04 | `grep \| awk` where a single `awk` suffices | Unnecessary pipe | | SH-m05 | Missing `command -v` check before using external tools | Fails confusingly if tool missing | | SH-m06 | Non-English log messages or comments | Language policy violation | @@ -56,9 +56,16 @@ rm -rf $name #!/usr/bin/env bash set -euo pipefail -local name="${1:?Missing required argument: name}" -cd /tmp || { echo "❌ Failed to cd /tmp"; exit 1; } -rm -rf "${name}" +process_directory() { + local base_dir="${1:?Missing base directory}" + local name="${2:?Missing name}" + + cd -- "$base_dir" || { + printf '❌ Failed to enter %s\n' "$base_dir" >&2 + return 1 + } + printf 'ℹ️ Processing %s\n' "$name" +} ``` ```bash @@ -74,6 +81,6 @@ process_file() { local count result=$(cat "$1") count=${#result} - echo "ℹ️ Processed ${count} bytes" + printf 'ℹ️ Processed %s bytes\n' "$count" } ``` diff --git a/.github/skills/internal-copilot-audit/SKILL.md b/.github/skills/internal-copilot-audit/SKILL.md index c60c3cc0..20736e92 100644 --- a/.github/skills/internal-copilot-audit/SKILL.md +++ b/.github/skills/internal-copilot-audit/SKILL.md @@ -73,6 +73,12 @@ For each finding, include: - proposed replacement or fix - tool-contract note when the issue involves explicit tool scope, MCP access, or legacy tool ids +### Review-lane projection + +When this audit runs inside a review lane, project `blocking` to `B` and +`non-blocking` to `S`. Keep the `Delete`, `Replace`, `Patch`, and `Keep` action inside the finding's +`Correction` field; it is not a second severity scale. + ## No-Fallback Rule When a repository-owned internal replacement exists, prefer deleting the weaker upstream asset instead of keeping a compatibility fallback. diff --git a/.github/skills/internal-ddd/SKILL.md b/.github/skills/internal-ddd/SKILL.md index b537b715..7ecdd5ce 100644 --- a/.github/skills/internal-ddd/SKILL.md +++ b/.github/skills/internal-ddd/SKILL.md @@ -10,7 +10,6 @@ description: Use when deciding whether a complex domain needs Domain-Driven Desi This index lists every other skill that this file asks the agent to load, route to, compare against, or delegate to. -- `internal-review-high-level`: incremental adoption review inside existing systems. - `internal-oop-design-patterns`: implementation-level pattern owner after tactical modeling. - `antigravity-api-design-principles`: API or contract design owner when bounded-context seams become interface work. @@ -57,7 +56,6 @@ Use this skill to decide how much Domain-Driven Design a problem deserves, then ## Adjacent lanes -- Use `internal-review-high-level` when the challenge is incremental adoption inside an existing system. - Use `internal-oop-design-patterns` when a tactical model now needs implementation-level pattern choices. - Use `antigravity-api-design-principles` when bounded-context seams are turning into API or contract design work. - Treat infrastructure boundaries as legitimate bounded-context candidates when the real seams are module ownership, environment contracts, or repo-level responsibility lines rather than object-oriented code. diff --git a/.github/skills/internal-debugging/SKILL.md b/.github/skills/internal-debugging/SKILL.md index 74c36731..c1472d01 100644 --- a/.github/skills/internal-debugging/SKILL.md +++ b/.github/skills/internal-debugging/SKILL.md @@ -14,7 +14,6 @@ next claim, or validated handoff. - `internal-review-code`: defect-first review when diagnosis exposes unsafe code or missing tests. - `internal-performance-optimization`: performance owner when measured slowness or throughput is primary. -- `internal-review-high-level`: systems review when diagnosis exposes architecture, workflow, or ownership gaps. - `internal-tdd`: regression-test owner after the root cause is understood. - `superpowers-systematic-debugging`: stricter diagnosis discipline for hard, flaky, or guess-prone failures. - `superpowers-verification-before-completion`: evidence gate before claiming the original loop is fixed. @@ -75,8 +74,6 @@ When an unexpected failure appears, stop adjacent feature work, preserve the cur root cause is understood. - `internal-review-code`: defect-first review when the diagnosis exposes a code smell, missing test, or unsafe fix. -- `internal-review-high-level`: architecture, workflow, or ownership gaps exposed - by missing seams, tangled callers, or cross-boundary drift. - Runtime-specific internal skills: language, workflow, Terraform, GitHub Actions, or script owners for idiomatic fixes and validation. diff --git a/.github/skills/internal-excel/SKILL.md b/.github/skills/internal-excel/SKILL.md index fe7e9064..7b85939c 100644 --- a/.github/skills/internal-excel/SKILL.md +++ b/.github/skills/internal-excel/SKILL.md @@ -1,37 +1,37 @@ --- name: internal-excel -description: Use when tasks involve CSV, TSV, or Excel tabular data profiling, schema validation, cleanup, joins, conversions, optimization, or large-file integrity. +description: Use when any task reads, creates, edits, validates, converts, or mentions an Excel workbook or an XLSX, XLSM, CSV, or TSV file. Load this skill first and keep it active even when formatting, charts, rendered review, or recalculation also require anthropic-xlsx. --- # Internal Excel ## Referenced skills -- `anthropic-xlsx`: on-demand support owner when rendered fidelity, cached recalculation, charts, or polished workbook presentation are the primary requirement. +- `anthropic-xlsx`: add alongside this skill when rendered fidelity, cached recalculation, charts, or polished workbook presentation are first-class requirements. ## When to use -- CSV, TSV, or `.xlsx` tasks centered on tabular data quality, profiling, schema choices, normalization, joins, dedupe, reconciliation, conversion, or large-file processing. +- Any request that reads, creates, edits, validates, converts, or mentions an Excel workbook or an XLSX, XLSM, CSV, or TSV file. +- CSV, TSV, `.xlsx`, or `.xlsm` tasks centered on tabular data quality, profiling, schema choices, normalization, joins, dedupe, reconciliation, conversion, or large-file processing. - Requests where the main decision is tool selection for scale, memory use, or integrity tradeoffs across local data files. - Workbook extraction, contract inspection, writer parity checks, or value-level updates where rendered presentation fidelity is not the primary requirement. - Requests to copy a workbook tab contract into generated tabs: column order, widths, header or body style, money style, alert or error row style, and formula columns. - Requests where derived workbook columns must stay as Excel formulas and raw source fields remain atomic input values. -## When not to use +## When to add adjacent skills -- Charts, rendered review, cached recalculation, or polished workbook presentation as a first-class delivery requirement; use `anthropic-xlsx`. -- Single-language implementation work after the tabular-data approach is already chosen; use the narrower file or runtime owner for that code. -- Database or warehouse design work that is not primarily about local CSV, TSV, or Excel artifacts. +- For charts, rendered review, cached recalculation, or polished workbook presentation, keep this skill active and add `anthropic-xlsx`. +- For single-language implementation work, add the narrower file or runtime owner while this skill retains the spreadsheet integrity contract. +- For database or warehouse design, add the relevant data-platform owner; keep this skill active only while local CSV, TSV, or Excel artifacts remain in scope. ## Boundary - This skill owns data integrity first: headers, types, nulls, duplicates, joins, reconciliation, stable IDs, delimiter detection, encoding, locale-sensitive numeric fields, and row-count preservation. - Keep evidence compact for large files: report headers, counts, targeted anomalies, transformation rules, exact validation gaps, and any locale or coercion assumptions that change numeric meaning. -- Treat `.xlsx` as a workbook container first. Stay here for tabular extraction, safe value-level transformation, workbook contract inspection, writer parity checks, and formula-column decisions. Route to `anthropic-xlsx` only when rendered fidelity, cached recalculation, charts, or presentation-preserving delivery is the main job. +- Treat `.xlsx` and `.xlsm` as workbook containers first. Stay here for tabular extraction, safe value-level transformation, workbook contract inspection, writer parity checks, and formula-column decisions. Add `anthropic-xlsx` while keeping this skill active when rendered fidelity, cached recalculation, charts, or presentation-preserving delivery is part of the job. - Preserve identifier fidelity before coercion: keep leading zeros, long numeric IDs, and day-first date text exact until an explicit schema rule says otherwise. -- Flag spreadsheet-bound text that could execute as a formula and minimize sensitive-column exposure in samples or logs. +- Flag spreadsheet-bound text that could execute as a formula and minimize sensitive-column exposure in samples or logs; apply the safeguards in `references/data-integrity-and-safety.md` when those risks are material. - Read `references/tool-selection.md` when choosing between Python `csv`, `pandas`, `openpyxl`, PyArrow, Polars, or DuckDB, or when scale, memory use, file format, or workbook fidelity makes the engine choice non-obvious. -- Read `references/data-integrity-and-safety.md` when delimiter or encoding detection, locale coercion, operation-specific proof, formula injection, or sensitive data exposure are material. - Read `references/large-file-token-discipline.md` when file size, broad profiling, repeated output, sampling strategy, or context pressure could make the tabular workflow expensive. ## Noise Exclusions @@ -40,19 +40,12 @@ description: Use when tasks involve CSV, TSV, or Excel tabular data profiling, s - Ignore workbook lock files such as `~$*` and `.~lock.*`. - Prefer targeted `rg` queries on source files, writer modules, and the named workbook path. Do not start with broad repo scans when the target file or owner path is already known. -## Workbook Token Gate - -- Before broad `.xlsx` reads, collect only bounded metadata: file size, sheet names, target-sheet dimensions, target headers, essential row counts, formula count, and style or style-id counts. -- Do not dump workbook XML, full worksheets, broad profiler output, or whole tables into chat unless they are the missing evidence. -- Read only the target sheets, columns, ranges, or writer blocks needed for the active question. -- Before opening large code modules, use `rg` to find owner functions, workbook writers, style builders, and formula helpers, then read only the needed blocks. - ## Workbook Contracts - When a sample workbook or sample tab defines the expected layout, treat that tab as a contract: column order, widths, header style, body style, money style, alert or error row style, and formula columns. - Verify that every tab produced by the same writer receives the same contract where applicable, not just the sampled tab. - When the user asks for verifiable formulas, keep derived columns as Excel formulas and keep source columns as atomic input values instead of precomputed results. -- If workbook behavior stays contract-level and formula-level, keep the guidance here. Route to `anthropic-xlsx` only when visual polish, charts, or recalculated delivery artifacts become primary. +- If workbook behavior stays contract-level and formula-level, keep the guidance here. Add `anthropic-xlsx` when visual polish, charts, or recalculated delivery artifacts become primary, without replacing this skill. ## Binary Artifacts @@ -60,32 +53,19 @@ description: Use when tasks involve CSV, TSV, or Excel tabular data profiling, s - If output validation needs a generated workbook, write it to `tmp/` or another declared controlled path and report that path. - Do not include Excel or LibreOffice lock files in discovery, validation, diffs, or deliverables. -## Runtime And Validation - -- If the local toolchain or bundle exposes a `.venv` or declared runtime, use that runtime for `py_compile`, tests, or `pytest` instead of ambient Python. -- Run the smallest deterministic validation that proves the workbook or tabular change; keep output bounded and artifact-oriented. - -## Token Discipline - -- Run a token budget gate before inspecting large or unknown-size files: capture file size, format, sheet names or delimiter, cheap row and column counts, headers, encoding clues, and the smallest representative sample needed. -- Do not paste full tables, raw workbook XML, full profiling JSON, or broad command output into chat by default. Report bounded summaries, counts, schema, anomalies, transformation rules, artifact paths, and validation gaps. -- Treat row samples as discovery only. Keep samples small and redacted, then prove transformations with full-file aggregate checks such as counts, key scans, coercion failures, or reconciliation queries. -- Prefer streaming reads, column projection, chunked scans, DuckDB, Polars, or PyArrow for large files. Use full `pandas` loads or full workbook traversal only after size and scope show that the token and memory cost is justified. -- For `.xlsx`, inspect workbook metadata first and read only the target sheets or ranges when possible. Do not escalate to broad workbook traversal unless the metadata gate shows it is necessary. -- Pause before expensive expansions such as dumping more rows, profiling every sheet, loading all columns, or running repeated wide joins. If the user explicitly asks for full output, state the context impact and provide the smallest bounded next slice or a local artifact path. - ## Workflow 1. Confirm the artifact type, row scale, token budget risk, whether workbook fidelity matters, and whether locale-specific numeric conventions or spreadsheet reopening are in play. 2. Pick the narrowest tool that preserves the needed integrity and performance. 3. Inspect headers, sample rows, counts, null patterns, key columns, and locale-sensitive numeric fields before broad transforms. -4. For `.xlsx`, inspect metadata and the active workbook contract before broad reads: sheet names, target dimensions, headers, formula counts, style counts, and the relevant writer blocks. +4. For `.xlsx` or `.xlsm`, inspect metadata and the active workbook contract before broad reads: sheet names, target dimensions, headers, formula counts, style counts, and the relevant writer blocks. 5. Apply deterministic transformations with explicit schema rules for IDs, dates, currency, and decimal text, and keep a reconciliation path for row counts, keys, duplicates, dropped records, and formula-column intent. 6. Re-run focused integrity and safety checks after each material transform or workbook-writer change. -7. Hand off only when rendered workbook polish, charts, cached recalculation, or presentation-preserving delivery becomes the main requirement. +7. Add `anthropic-xlsx` when rendered workbook polish, charts, cached recalculation, or presentation-preserving delivery is required, and keep this skill active as the spreadsheet entry point. ## Validation +- If the local toolchain or bundle exposes a `.venv` or declared runtime, use that runtime for validation instead of ambient Python. - Run the smallest deterministic check that proves the transform: row counts, schema diff, duplicate-key scan, delimiter or encoding confirmation, locale-sensitive numeric confirmation, join cardinality, or a reconciliation sample. - For large files, validation output must stay compact: full-file checks should produce aggregate evidence, anomaly counts, sampled examples only when needed, and paths to generated reports instead of inline dumps. - When data may return to spreadsheet tools, verify formula-injection handling and avoid exposing raw sensitive values in samples or validation output. diff --git a/.github/skills/internal-excel/agents/openai.yaml b/.github/skills/internal-excel/agents/openai.yaml index 2770b088..c22eea7b 100644 --- a/.github/skills/internal-excel/agents/openai.yaml +++ b/.github/skills/internal-excel/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Internal Excel" - short_description: "Tabular data profiling and cleanup" - default_prompt: "Use $internal-excel for CSV, TSV, or Excel tabular data profiling, schema checks, cleanup, conversions, and large-file transformations." + short_description: "Universal Excel and tabular-data entry point" + default_prompt: "Use $internal-excel as the primary entry point for any Excel, XLSX, XLSM, CSV, or TSV task, adding anthropic-xlsx when workbook presentation or recalculation is required." diff --git a/.github/skills/internal-excel/references/tool-selection.md b/.github/skills/internal-excel/references/tool-selection.md index 2117e176..eb2f2d68 100644 --- a/.github/skills/internal-excel/references/tool-selection.md +++ b/.github/skills/internal-excel/references/tool-selection.md @@ -12,7 +12,7 @@ Read this reference when scale, file format, or workbook fidelity makes the engi | Columnar scans, type-stable interchange, Parquet or Arrow conversion | PyArrow | Strong schema control and efficient IO | Prefer when conversion fidelity and explicit types matter. | | Large in-memory transforms with strict schema and speed focus | Polars | Fast columnar execution | Prefer when `pandas` becomes memory-heavy or slow. | | Reading or updating `.xlsx` cell values while workbook UX is secondary | `openpyxl` | Native workbook access | Stay here only when layout, styles, and rendered review are not the main goal. | -| Formulas, styles, charts, cached recalculation, rendered review, workbook preservation | `anthropic-xlsx` | Workbook UX owner | Route out of this skill. | +| Formulas, styles, charts, cached recalculation, rendered review, workbook preservation | `anthropic-xlsx` | Workbook UX owner | Add alongside this skill. | ## Selection rules @@ -22,9 +22,9 @@ Read this reference when scale, file format, or workbook fidelity makes the engi - Prefer DuckDB, Polars, or PyArrow when file size or join volume makes full `pandas` loads risky. - Prefer engines that support explicit schema declarations when inference could corrupt IDs, dates, currency, or nullable numeric fields. -## Escalation to `anthropic-xlsx` +## Adding `anthropic-xlsx` -Route to `anthropic-xlsx` when any of these are first-class requirements: +Keep `internal-excel` active as the entry point and add `anthropic-xlsx` when any of these are first-class requirements: - formulas or cached recalculation - charts or workbook layout diff --git a/.github/skills/internal-gateway-critical-master/SKILL.md b/.github/skills/internal-gateway-critical-master/SKILL.md index ef6f0145..c255e022 100644 --- a/.github/skills/internal-gateway-critical-master/SKILL.md +++ b/.github/skills/internal-gateway-critical-master/SKILL.md @@ -19,6 +19,7 @@ gateway decides when to invoke it; this skill challenges only. ## When not to use - The next step is retained planning, implementation, or evidence-first review. +- This skill is not an automatic counter-analysis step for evidence-first review. ## Boundaries @@ -34,6 +35,9 @@ Run exactly three phases. Do not skip a phase and do not loop back unless new ev - Identify the material claims, constraints, success criteria, and anti-scope. - Record internally: what is being challenged and why it matters now. +Completion criterion: the challenged target, material claims, constraints, +success criteria, anti-scope, and evidence gaps are recorded. + ### Phase 2: Challenge - Select exactly **three lenses** from the table below based on the highest-risk gaps in the summary. @@ -43,6 +47,9 @@ Run exactly three phases. Do not skip a phase and do not loop back unless new ev - Ask at most one concise root question across all findings when the answer would materially change the critique. - Treat mitigations as conditions to continue, not as implementation designs that rescue the proposal. +Completion criterion: exactly three lenses were applied, the third is lateral, +and the strongest supported objection controls the result. + | Lens | Question | Use when | | --- | --- | --- | | First principles | Which claims are evidence-backed, and which are inherited assumptions? | The plan repeats local habits as if they were constraints. | @@ -70,6 +77,9 @@ Trigger a pre-mortem when at least one of these is true: - When Defense is not `none`, name the strongest defense and the remaining vulnerability inside the synthesis. - Select exactly one canonical routing outcome from `## Outcome meanings`. +Completion criterion: defense, residual uncertainty, and exactly one canonical +outcome are resolved. + ## Internal critical record Keep the following as internal working state. Do not print the internal critical record in normal chat; use it to produce the public card. @@ -101,7 +111,6 @@ In normal chat, emit only the localized three-to-five-line emoji card defined in - Optional: `scripts/validate_critical_output.py` checks a rendered card against the contract in `references/output-contract.md`. - The optional validator and its pure helper live inside this skill bundle so the skill can be copied without depending on repo-global Python modules. - Reuse `fixtures/critical_output_valid.md` and sibling fixture samples instead of repeating long inline payloads. -- Follow `references/maintenance-guidance.md` for fixture reuse and cache-aware search discipline. - Keep this bundle self-contained: do not require instructions, examples, or enforcement rules from outside this directory. - Script output contract: `text` for short operator summaries (default), `json` for nested or machine-consumed output, `compact` for status and counts; validation findings on stdout, file and usage failures on stderr; keep output bounded. diff --git a/.github/skills/internal-gateway-critical-master/references/maintenance-guidance.md b/.github/skills/internal-gateway-critical-master/references/maintenance-guidance.md deleted file mode 100644 index 2d7d5e7f..00000000 --- a/.github/skills/internal-gateway-critical-master/references/maintenance-guidance.md +++ /dev/null @@ -1,4 +0,0 @@ -# Maintenance Guidance - -- Prefer `fixtures/` samples over repeated inline Markdown payloads. -- When the target is tracked source, exclude generated caches such as `graphify-out/`, `.pytest_cache/`, `.venv/`, and `__pycache__/` from broad searches. diff --git a/.github/skills/internal-gateway-critical-master/scripts/critical_master.py b/.github/skills/internal-gateway-critical-master/scripts/critical_master.py index 23ca9015..81d2b545 100644 --- a/.github/skills/internal-gateway-critical-master/scripts/critical_master.py +++ b/.github/skills/internal-gateway-critical-master/scripts/critical_master.py @@ -22,22 +22,6 @@ } ) -ALLOWED_CLAIM_CLASSES: frozenset[str] = frozenset( - {"confirmed", "inference", "estimate"} -) - -ALLOWED_EVIDENCE_QUALITY: frozenset[str] = frozenset( - {"strong", "partial", "weak"} -) - -ALLOWED_LIKELIHOODS: frozenset[str] = frozenset({"high", "medium", "low"}) - -ALLOWED_DEFENSE_VALUES: frozenset[str] = frozenset( - {"none", "resolves", "narrows", "accepts-risk", "unanswered"} -) - -TOTAL_MAX_WORDS = 600 - REQUIRED_CARD_MARKERS = ("🎯", "⚠️", "✅") OPTIONAL_CARD_MARKERS = ("💥", "❓") CARD_MARKER_ORDER = ("🎯", "⚠️", "💥", "✅", "❓") @@ -127,10 +111,6 @@ def validate_outcome_value(value: str) -> bool: __all__ = [ - "ALLOWED_CLAIM_CLASSES", - "ALLOWED_DEFENSE_VALUES", - "ALLOWED_EVIDENCE_QUALITY", - "ALLOWED_LIKELIHOODS", "ALLOWED_OUTCOMES", "CARD_LINE_MAX_WORDS", "CARD_MARKER_ORDER", @@ -142,7 +122,6 @@ def validate_outcome_value(value: str) -> bool: "Finding", "OPTIONAL_CARD_MARKERS", "REQUIRED_CARD_MARKERS", - "TOTAL_MAX_WORDS", "count_words", "parse_critical_card", "validate_outcome_value", diff --git a/.github/skills/internal-gateway-execute-plans/scripts/plan_execution.py b/.github/skills/internal-gateway-execute-plans/scripts/plan_execution.py index ba3925f6..a6605981 100644 --- a/.github/skills/internal-gateway-execute-plans/scripts/plan_execution.py +++ b/.github/skills/internal-gateway-execute-plans/scripts/plan_execution.py @@ -27,10 +27,13 @@ class Finding: REQUIRED_PLAN_HEADINGS = ( "Goal", - "Repository Preflight", "Global Constraints", ) +PLAN_HEADING_ALIASES = { + "Repository Preflight": ("Repository Preflight", "Preflight"), +} + REQUIRED_STATUS_HEADINGS = ( "Status", "Plan", @@ -104,6 +107,15 @@ def validate_plan(path: Path, repo_root: Path) -> list[Finding]: Finding("missing-heading", f"Plan missing required heading: {required}") ) + for canonical, aliases in PLAN_HEADING_ALIASES.items(): + if not any(alias in heading_set for alias in aliases): + findings.append( + Finding( + "missing-heading", + f"Plan missing required heading: {canonical}", + ) + ) + if "Task" not in " ".join(headings) and "## Task" not in text: findings.append( Finding("missing-task", "Plan must contain at least one task heading") diff --git a/.github/skills/internal-gateway-idea/SKILL.md b/.github/skills/internal-gateway-idea/SKILL.md index 79be54f0..ac69dcc1 100644 --- a/.github/skills/internal-gateway-idea/SKILL.md +++ b/.github/skills/internal-gateway-idea/SKILL.md @@ -1,7 +1,6 @@ --- name: internal-gateway-idea description: Use when a repository-owned idea needs brainstorming, assumption challenge, alternative discovery, and a spec-vs-plan recommendation before implementation planning. -disable-model-invocation: true --- # Internal Gateway Idea @@ -16,7 +15,7 @@ disable-model-invocation: true - `references/workflow.md`: authoritative state machine, Mermaid workflow, approval rules, routing stability, and scoped local validation lane for this bundle. -- `scripts/audit_workflow.py`: marker-consistency validator; run via `python3 .github/skills/internal-gateway-idea/scripts/audit_workflow.py` or `make internal-gateway-idea-fast-check`. +- `scripts/audit_workflow.py`: marker-consistency validator; run via `python3 .github/skills/internal-gateway-idea/scripts/audit_workflow.py`. - Script output contract: `text` for short operator summaries (default), `json` for nested or machine-consumed output, `tsv`/`csv` only for large flat tables; data on stdout, diagnostics on stderr; keep output bounded. Lightweight repository-owned wrapper for idea shaping. Use `/superpowers-brainstorming` as the core workflow and add the local gates below. Loading `/superpowers-brainstorming` is an intentional, globally-resolvable exception to the bundle self-containment rule. This skill does not replace the core brainstorming process; it constrains it for repository-owned idea work. diff --git a/.github/skills/internal-gateway-idea/references/workflow.md b/.github/skills/internal-gateway-idea/references/workflow.md index 209e1a38..1e39e7c4 100644 --- a/.github/skills/internal-gateway-idea/references/workflow.md +++ b/.github/skills/internal-gateway-idea/references/workflow.md @@ -84,6 +84,6 @@ and user decisions remain visible. ## Local validation lane -Run `python3 .github/skills/internal-gateway-idea/scripts/audit_workflow.py` or `make internal-gateway-idea-fast-check` before widening to catalog-wide checks. This scoped lane must cover the bundle audit and marker consistency. +Run `python3 .github/skills/internal-gateway-idea/scripts/audit_workflow.py` before widening to catalog-wide checks. This scoped lane must cover the bundle audit and marker consistency. The checkpoint must use one bounded research question; do not start a second research pass automatically. diff --git a/.github/skills/internal-gateway-simple-task/SKILL.md b/.github/skills/internal-gateway-simple-task/SKILL.md index 5dc071eb..134fc9e4 100644 --- a/.github/skills/internal-gateway-simple-task/SKILL.md +++ b/.github/skills/internal-gateway-simple-task/SKILL.md @@ -74,7 +74,7 @@ For `full-gate`, complete the gates in this order: 1. Inspect the nearest local evidence. 2. Confirm the task still fits one bounded run. 3. Complete Initial Idea Ordering. -4. Ask one compact `/grill-me` block only when a missing bounded fact blocks the active lane. Use `/grill-me` only when a missing bounded fact blocks the active lane. +4. Ask one compact `/grill-me` block only when a missing bounded fact blocks the active lane. 5. Run `/internal-gateway-critical-master` before non-trivial action. 6. Write a short Readiness Brief. 7. If executable or evaluable behavior changes, load `/internal-tdd` before implementation and follow its routed posture. diff --git a/.github/skills/internal-gateway-simple-task/scripts/resolve_simple_task.py b/.github/skills/internal-gateway-simple-task/scripts/resolve_simple_task.py index 4347b7e8..908bc8e7 100644 --- a/.github/skills/internal-gateway-simple-task/scripts/resolve_simple_task.py +++ b/.github/skills/internal-gateway-simple-task/scripts/resolve_simple_task.py @@ -192,7 +192,8 @@ def detect_depth_keywords(prompt: str, explicit_keywords: list[str]) -> list[str found = set(explicit_keywords) lowered_prompt = prompt.lower() for keyword in DEPTH_KEYWORDS: - if re.search(rf"\b{re.escape(keyword)}\b", lowered_prompt): + explicit_prompt = rf"(?:/{re.escape(keyword)}\b|\b(?:depth|mode|gate)\s*[:=]\s*{re.escape(keyword)}\b|\b{re.escape(keyword)}\s+(?:gate|mode|workflow)\b)" + if re.search(explicit_prompt, lowered_prompt): found.add(keyword) return sorted(found) @@ -337,8 +338,6 @@ def build_gate_decision( if missing_validation_evidence: reason_codes.append("validation-path-missing") blocking_reasons.append("validation-path-missing") - if validation_obvious and missing_validation_evidence: - reason_codes.append("validation-path-missing") if blocking_reasons: gate_outcome = "stop-with-reason" diff --git a/.github/skills/internal-gcp/SKILL.md b/.github/skills/internal-gcp/SKILL.md index dbc746ba..43f8ca59 100644 --- a/.github/skills/internal-gcp/SKILL.md +++ b/.github/skills/internal-gcp/SKILL.md @@ -164,4 +164,4 @@ Include: - Confirm assumptions, active lenses, and the main tradeoff are named instead of implied. - Confirm the recommendation includes reversibility or blast-radius guidance when the choice is hard to unwind. - Confirm cost-value or operational impact is called out when it materially changes the recommendation. -- Confirm the answer states when freshness matters and which current Google Cloud fact still needs validation. \ No newline at end of file +- Confirm the answer states when freshness matters and which current Google Cloud fact still needs validation. diff --git a/.github/skills/internal-gcp/references/routing-matrix.md b/.github/skills/internal-gcp/references/routing-matrix.md index 7b5371a3..a17f1cea 100644 --- a/.github/skills/internal-gcp/references/routing-matrix.md +++ b/.github/skills/internal-gcp/references/routing-matrix.md @@ -26,4 +26,4 @@ ## Review rule -Prefer a direct specialist whenever a reasonable reviewer can name one primary owner from the request itself. Activate the fallback only when the request does not identify a primary owner and clarification is required before a specialist can engage. The fallback is not a prerequisite for ordinary GCP work and must never activate all GCP skills by default. \ No newline at end of file +Prefer a direct specialist whenever a reasonable reviewer can name one primary owner from the request itself. Activate the fallback only when the request does not identify a primary owner and clarification is required before a specialist can engage. The fallback is not a prerequisite for ordinary GCP work and must never activate all GCP skills by default. diff --git a/.github/skills/internal-json/SKILL.md b/.github/skills/internal-json/SKILL.md index 5fde936a..fc5cf38c 100644 --- a/.github/skills/internal-json/SKILL.md +++ b/.github/skills/internal-json/SKILL.md @@ -1,36 +1,46 @@ --- name: internal-json -description: Use when editing repository-owned JSON registry, organization, data, or configuration files that need formatting and consistency rules. +description: Use when editing or reviewing strict JSON grammar, encoding, duplicate names, numeric interoperability, or format-owner routing. --- # Internal JSON -## Referenced skills - -- None. - ## When to use -- JSON under registry-like, organization, source, or data paths. -- Repository-owned JSON configuration where no ecosystem-specific owner is stronger. -- Reviews focused on indentation, key order, schema fit, and stable machine-readable structure. +- JSON edits where strict grammar and interoperable representation are the + active concern. +- Reviews focused on UTF-8, BOM handling, duplicate object names, ordering + semantics, numeric portability, and parser-safe strings. +- Routing a file to a stronger ecosystem or domain owner when its semantics + are the real concern. ## When not to use -- `package.json`, lock files, or ecosystem-managed JSON with stronger local conventions. -- JSON embedded in Terraform, Kubernetes, or cloud policy work where that domain owner decides the schema. -- Generated JSON unless the task explicitly asks to regenerate or validate it. +- Ecosystem-managed JSON whose owner defines a stronger contract. +- JSON embedded in another domain where that domain owner decides the schema. +- Generated JSON unless the task explicitly asks for format validation. ## Baseline -- Use 2-space indentation. -- Do not use trailing commas. -- Preserve ecosystem or generator ordering when a tool owns the file. -- Keep keys alphabetical only when the local file pattern already does that or the schema expects it. -- Validate schema when one exists. -- Use technical English for descriptive fields intended for operator output. +- Use strict JSON syntax and grammar: no comments, trailing commas, or non-standard + constants. +- Decode as UTF-8 without a BOM and reject duplicate object names. +- Preserve object order as presentation; JSON object order is not semantic. +- Keep integers within interoperable binary64-safe bounds and reject finite + numbers outside binary64 range. ## Validation -- Run `python -m json.tool ` or the repository JSON validator when no narrower check exists. -- Run the owning schema or focused test when the JSON participates in a registry or generated contract. +Run the bundle-owned checker with explicit files: + +```bash +python3 .github/skills/internal-json/scripts/check.py FILE [FILE ...] +``` + +The checker returns `0` when checks passed within supported scope, `1` for +format findings, and `2` for usage, dependency, file, or internal failures. +It uses Python 3.10+ standard-library parsing and does not install +dependencies. Supported checks include strict grammar, UTF-8/BOM handling, +duplicate names via `object_pairs_hook`, non-standard constants, unpaired +surrogates, and numeric interoperability. Schema and content semantics are +unsupported; route them to the domain owner. diff --git a/.github/skills/internal-json/agents/openai.yaml b/.github/skills/internal-json/agents/openai.yaml index e5f9c925..1361c549 100644 --- a/.github/skills/internal-json/agents/openai.yaml +++ b/.github/skills/internal-json/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Internal JSON" - short_description: "JSON formatting and registry rules" - default_prompt: "Use $internal-json for repository-owned JSON registry, organization, data, or configuration files." + short_description: "Strict JSON format handling" + default_prompt: "Use $internal-json when editing or reviewing JSON syntax, encoding, duplicate keys, numeric portability, or format-owner routing." diff --git a/.github/skills/internal-json/fixtures/invalid/duplicate-nested.json b/.github/skills/internal-json/fixtures/invalid/duplicate-nested.json new file mode 100644 index 00000000..b189a0c4 --- /dev/null +++ b/.github/skills/internal-json/fixtures/invalid/duplicate-nested.json @@ -0,0 +1 @@ +{"outer": {"value": 1, "value": 2}} diff --git a/.github/skills/internal-json/fixtures/invalid/duplicate-root.json b/.github/skills/internal-json/fixtures/invalid/duplicate-root.json new file mode 100644 index 00000000..445cedc9 --- /dev/null +++ b/.github/skills/internal-json/fixtures/invalid/duplicate-root.json @@ -0,0 +1 @@ +{"name": "first", "name": "second"} diff --git a/.github/skills/internal-json/fixtures/invalid/non-finite.json b/.github/skills/internal-json/fixtures/invalid/non-finite.json new file mode 100644 index 00000000..a73b6613 --- /dev/null +++ b/.github/skills/internal-json/fixtures/invalid/non-finite.json @@ -0,0 +1 @@ +{"not_a_number": NaN, "positive": Infinity, "negative": -Infinity} diff --git a/.github/skills/internal-json/fixtures/invalid/overflow-number.json b/.github/skills/internal-json/fixtures/invalid/overflow-number.json new file mode 100644 index 00000000..b31c0dca --- /dev/null +++ b/.github/skills/internal-json/fixtures/invalid/overflow-number.json @@ -0,0 +1 @@ +{"overflow": 1e400} diff --git a/.github/skills/internal-json/fixtures/invalid/unsafe-integer.json b/.github/skills/internal-json/fixtures/invalid/unsafe-integer.json new file mode 100644 index 00000000..d23c14cd --- /dev/null +++ b/.github/skills/internal-json/fixtures/invalid/unsafe-integer.json @@ -0,0 +1 @@ +{"unsafe": 9007199254740992} diff --git a/.github/skills/internal-json/fixtures/valid/nested.json b/.github/skills/internal-json/fixtures/valid/nested.json new file mode 100644 index 00000000..2f82a265 --- /dev/null +++ b/.github/skills/internal-json/fixtures/valid/nested.json @@ -0,0 +1,10 @@ +{ + "name": "nested", + "enabled": true, + "count": 42, + "ratio": 1.5, + "items": [ + {"id": "one", "values": [null, false]}, + {"id": "two", "values": [0, -3.25]} + ] +} diff --git a/.github/skills/internal-json/references/validation-contract.md b/.github/skills/internal-json/references/validation-contract.md new file mode 100644 index 00000000..01c806ac --- /dev/null +++ b/.github/skills/internal-json/references/validation-contract.md @@ -0,0 +1,23 @@ +# JSON validation contract + +Run the checker with Python 3.10 or newer and explicit JSON paths: + +```bash +python3 .github/skills/internal-json/scripts/check.py [--format text|json] FILE [FILE ...] +``` + +The script uses only the Python standard library and never installs +dependencies. It is read-only, checks at most 100 findings, and returns `0` +when checks passed within supported scope, `1` for format findings, and `2` +for usage, file, or internal failures. `--self-test` checks the bundled +fixtures. + +Supported findings are `JSON_BOM`, `JSON_ENCODING`, `JSON_SYNTAX`, +`JSON_DUPLICATE_KEY`, `JSON_NON_FINITE`, `JSON_UNSAFE_INTEGER`, +`JSON_NUMBER_RANGE`, and `JSON_UNPAIRED_SURROGATE`. Integers must remain within +`[-9007199254740991, 9007199254740991]`; finite numbers must remain within the +IEEE-754 binary64 maximum magnitude. + +The checker does not validate schemas, required properties, business meaning, +registry or organization rules, generated-content policy, or other domain +semantics. Route those concerns to the owning domain skill. diff --git a/.github/skills/internal-json/scripts/check.py b/.github/skills/internal-json/scripts/check.py new file mode 100644 index 00000000..c073567c --- /dev/null +++ b/.github/skills/internal-json/scripts/check.py @@ -0,0 +1,333 @@ +#!/usr/bin/env python3 +"""Strict, read-only JSON format checker using only the Python standard library.""" +from __future__ import annotations + +import argparse +import codecs +import decimal +import json +import sys +from dataclasses import dataclass +from pathlib import Path + +MAX_FINDINGS = 100 +MAX_SAFE_INTEGER = 2**53 - 1 +MAX_BINARY64 = decimal.Decimal(str(sys.float_info.max)) + + +@dataclass(frozen=True) +class Finding: + code: str + source: str + path: str + line: int | None + column: int | None + message: str + + +@dataclass(frozen=True) +class JsonNumber: + raw: str + integer: bool + + +@dataclass(frozen=True) +class JsonObject: + pairs: list[tuple[str, object]] + + +def _append_finding( + findings: list[Finding], + code: str, + source: str, + path: str, + message: str, + line: int | None = None, + column: int | None = None, +) -> None: + if len(findings) < MAX_FINDINGS: + findings.append(Finding(code, source, path, line, column, message)) + + +def _member_path(path: str, key: str) -> str: + return f"{path}[{json.dumps(key, ensure_ascii=True)}]" + + +def _contains_surrogate(value: str) -> bool: + return any(0xD800 <= ord(character) <= 0xDFFF for character in value) + + +def _integer_exceeds_safe_limit(raw: str) -> bool: + digits = raw[1:] if raw.startswith("-") else raw + safe_limit = str(MAX_SAFE_INTEGER) + return len(digits) > len(safe_limit) or ( + len(digits) == len(safe_limit) and digits > safe_limit + ) + + +def _check_number( + number: JsonNumber, source: str, path: str, findings: list[Finding] +) -> None: + try: + if number.integer: + if _integer_exceeds_safe_limit(number.raw): + _append_finding( + findings, + "JSON_UNSAFE_INTEGER", + source, + path, + f"integer magnitude exceeds {MAX_SAFE_INTEGER}", + ) + return + + value = decimal.Decimal(number.raw) + except decimal.InvalidOperation: + _append_finding( + findings, + "JSON_SYNTAX", + source, + path, + "number could not be interpreted", + ) + return + + if value.is_finite() and abs(value) > MAX_BINARY64: + _append_finding( + findings, + "JSON_NUMBER_RANGE", + source, + path, + "finite number exceeds IEEE-754 binary64 range", + ) + + +def _inspect_value( + value: object, source: str, path: str, findings: list[Finding] +) -> None: + if len(findings) >= MAX_FINDINGS: + return + if isinstance(value, JsonObject): + seen: set[str] = set() + for key, child in value.pairs: + child_path = _member_path(path, key) + if key in seen: + _append_finding( + findings, + "JSON_DUPLICATE_KEY", + source, + path, + f"object name {key!r} is repeated", + ) + seen.add(key) + if _contains_surrogate(key): + _append_finding( + findings, + "JSON_UNPAIRED_SURROGATE", + source, + child_path, + "string contains an unpaired UTF-16 surrogate", + ) + _inspect_value(child, source, child_path, findings) + return + if isinstance(value, list): + for index, child in enumerate(value): + _inspect_value(child, source, f"{path}[{index}]", findings) + return + if isinstance(value, str) and _contains_surrogate(value): + _append_finding( + findings, + "JSON_UNPAIRED_SURROGATE", + source, + path, + "string contains an unpaired UTF-16 surrogate", + ) + elif isinstance(value, JsonNumber): + _check_number(value, source, path, findings) + + +def _line_column(text: str, position: int) -> tuple[int, int]: + line = text.count("\n", 0, position) + 1 + previous_newline = text.rfind("\n", 0, position) + return line, position - previous_newline + + +def _byte_line_column(data: bytes, byte_position: int) -> tuple[int, int]: + valid_prefix = data[:byte_position].decode("utf-8", errors="strict") + return _line_column(valid_prefix, len(valid_prefix)) + + +def check_bytes(data: bytes, path: str) -> list[Finding]: + findings: list[Finding] = [] + if data.startswith(codecs.BOM_UTF8): + _append_finding( + findings, + "JSON_BOM", + path, + "$", + "UTF-8 BOM is not allowed", + 1, + 1, + ) + return findings + + try: + text = data.decode("utf-8", errors="strict") + except UnicodeDecodeError as error: + line, column = _byte_line_column(data, error.start) + _append_finding( + findings, + "JSON_ENCODING", + path, + "$", + "input is not valid UTF-8", + line, + column, + ) + return findings + + def parse_constant(raw: str) -> JsonNumber: + _append_finding( + findings, + "JSON_NON_FINITE", + path, + "$", + f"non-standard constant {raw} is not allowed", + ) + return JsonNumber(raw, integer=False) + + try: + value = json.loads( + text, + object_pairs_hook=JsonObject, + parse_int=lambda raw: JsonNumber(raw, integer=True), + parse_float=lambda raw: JsonNumber(raw, integer=False), + parse_constant=parse_constant, + ) + except json.JSONDecodeError as error: + _append_finding( + findings, + "JSON_SYNTAX", + path, + "$", + error.msg, + error.lineno, + error.colno, + ) + return findings + + _inspect_value(value, path, "$", findings) + return findings + + +def check_file(path: Path) -> list[Finding]: + try: + data = path.read_bytes() + except OSError as error: + raise OSError(f"unable to read input file {path}: {error}") from error + return check_bytes(data, str(path)) + + +def _render_text(findings: list[Finding]) -> str: + if not findings: + return "checks passed within supported scope\n" + lines = [] + for finding in findings: + location = finding.source + if finding.line is not None and finding.column is not None: + location += f":{finding.line}:{finding.column}" + lines.append(f"{location} {finding.path} {finding.code}: {finding.message}") + return "\n".join(lines) + "\n" + + +def _render_json(findings: list[Finding], files_checked: int) -> str: + return json.dumps( + { + "status": "passed" if not findings else "findings", + "files_checked": files_checked, + "findings_count": len(findings), + "findings": [ + { + "code": finding.code, + "source": finding.source, + "path": finding.path, + "line": finding.line, + "column": finding.column, + "message": finding.message, + } + for finding in findings + ], + }, + ensure_ascii=True, + sort_keys=False, + ) + "\n" + + +def _run_self_test(script_path: Path) -> int: + fixture_root = script_path.parent.parent / "fixtures" + valid = fixture_root / "valid/nested.json" + invalid = [ + fixture_root / "invalid/duplicate-root.json", + fixture_root / "invalid/duplicate-nested.json", + fixture_root / "invalid/non-finite.json", + fixture_root / "invalid/unsafe-integer.json", + fixture_root / "invalid/overflow-number.json", + ] + try: + if check_file(valid): + print("error: JSON self-test valid fixture produced findings", file=sys.stderr) + return 2 + for path in invalid: + if not check_file(path): + print(f"error: JSON self-test invalid fixture passed: {path}", file=sys.stderr) + return 2 + except OSError as error: + print(f"error: {error}", file=sys.stderr) + return 2 + print("JSON self-test passed") + return 0 + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser( + description="Check strict JSON format constraints for explicit files" + ) + parser.add_argument("--format", choices=("text", "json"), default="text") + parser.add_argument("--self-test", action="store_true") + parser.add_argument("files", nargs="*") + args = parser.parse_args(argv) + + if args.self_test: + if args.files: + parser.error("--self-test does not accept input files") + return _run_self_test(Path(__file__).resolve()) + if not args.files: + parser.error("at least one input file is required") + + findings: list[Finding] = [] + files_checked = 0 + try: + for name in args.files: + path = Path(name) + if not path.is_file(): + print(f"error: input file not found: {name}", file=sys.stderr) + return 2 + files_checked += 1 + for finding in check_file(path): + if len(findings) < MAX_FINDINGS: + findings.append(finding) + except OSError as error: + print(f"error: {error}", file=sys.stderr) + return 2 + except Exception as error: # pragma: no cover - defensive CLI boundary + print(f"error: internal checker failure: {error}", file=sys.stderr) + return 2 + + if args.format == "json": + sys.stdout.write(_render_json(findings, files_checked)) + else: + sys.stdout.write(_render_text(findings)) + return 1 if findings else 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/.github/skills/internal-kubernetes-deployment/SKILL.md b/.github/skills/internal-kubernetes-deployment/SKILL.md index 1cec5102..5e9d2fa6 100644 --- a/.github/skills/internal-kubernetes-deployment/SKILL.md +++ b/.github/skills/internal-kubernetes-deployment/SKILL.md @@ -8,7 +8,7 @@ description: Use when authoring or reviewing Kubernetes workload manifests, serv ## Referenced skills - `internal-kubernetes`: Kubernetes umbrella lane selection when ownership is not already clear. -- `internal-yaml`: YAML formatting and schema awareness baseline. +- `internal-yaml`: YAML formatting and parser-safety baseline. Use this skill for operational Kubernetes delivery work after the platform direction is already known. @@ -48,7 +48,7 @@ Use this skill for operational Kubernetes delivery work after the platform direc - Prefer raw manifests by default; add Helm only when repeated installs, versioned packaging, or environment overlays justify chart maintenance. - Treat service mesh integration as conditional: configure traffic policy, mTLS, and mesh telemetry only when the cluster already runs a mesh or the platform standard requires it. - Prefer controller-driven delivery such as GitOps only when the team already operates that model and the rollout ownership is explicit. -- Load `internal-yaml` for YAML formatting and schema-awareness checks when manifest syntax, indentation, or parser behavior is the main issue. +- Load `internal-yaml` for YAML formatting and parser checks when manifest syntax, indentation, or parser behavior is the main issue. ## Operational Rules diff --git a/.github/skills/internal-kubernetes/SKILL.md b/.github/skills/internal-kubernetes/SKILL.md index 44b93eb9..eea1a1df 100644 --- a/.github/skills/internal-kubernetes/SKILL.md +++ b/.github/skills/internal-kubernetes/SKILL.md @@ -11,7 +11,7 @@ Treat the referenced skills below as on-demand owners. Do not preload the whole Kubernetes family; load them only when the request proves whether syntax, workload delivery, or platform architecture is the real problem. -- `internal-yaml`: YAML formatting and schema-awareness baseline when manifest syntax itself is the blocker. +- `internal-yaml`: YAML formatting and parser-safety baseline when manifest syntax itself is the blocker. - `internal-kubernetes-deployment`: workload manifests, service exposure, probes, autoscaling, rollout strategy, and production hardening when delivery semantics are the task. - `antigravity-kubernetes-architect`: Kubernetes platform architecture, GitOps operating model, service mesh, and multi-cluster strategy when platform shape is the task. diff --git a/.github/skills/internal-makefile/SKILL.md b/.github/skills/internal-makefile/SKILL.md index b445e676..e8a9aec3 100644 --- a/.github/skills/internal-makefile/SKILL.md +++ b/.github/skills/internal-makefile/SKILL.md @@ -1,37 +1,48 @@ --- name: internal-makefile -description: Use when editing Makefile or .mk files that need deterministic targets, readable recipes, and phony target hygiene. +description: Use when editing or reviewing Makefile or .mk syntax, targets, prerequisites, recipes, variables, or static format checks. --- # Internal Makefile -## Referenced skills - -- None. - ## When to use -- `Makefile` or `*.mk` changes. -- Reviews of target naming, phony declarations, recipe clarity, and deterministic command behavior. -- Small build-orchestration edits that do not belong to a narrower runtime or CI owner. +- Makefile or `.mk` edits where static Make format ownership is the active + concern. +- Reviews of targets, prerequisites, recipe prefixes, `.PHONY`, variables, + and `$` versus `$$`. +- Reviews of safe static validation and routing when embedded shell behavior + dominates. ## When not to use -- CI workflow semantics are the main concern; use the matching CI owner. -- The Make target only wraps a script whose behavior is owned by a language or script skill. +- Embedded shell behavior dominates the recipe; use `/internal-bash`. +- CI or runtime semantics are the main concern; use the matching owner. - Generated Makefiles unless the generator is the intended edit point. ## Baseline -- Use lowercase, hyphenated target names. - Mark non-file targets with `.PHONY`. -- Keep common variables near the top. -- Prefer a `help` target when the Makefile is operator-facing. -- Keep recipes readable and deterministic. -- Avoid hidden side effects in the default target. +- Keep prerequisites, order-only prerequisites, variables, and recipes + explicit and readable. +- Preserve tab-prefixed recipes and distinguish Make variables (`$`) from + shell variables (`$$`). +- Treat recursive Make, parallelism, recipe side effects, and domain behavior + as review concerns. +- `make` and `make -n` are not generic safety boundaries; `make -n` is only a + preview, so inspect recipes before execution. ## Validation -- Run the touched target when it is safe and deterministic. -- Use `make -n ` when execution would mutate state. -- Run the nearest focused test when a target is part of validator behavior. +Run the bundle-owned static checker with explicit files: + +```bash +.github/skills/internal-makefile/scripts/check.sh FILE [FILE ...] +``` + +The checker returns `0` when checks passed within supported scope, `1` for +format findings, and `2` for usage, dependency, file, or internal failures. +It requires `checkmake` 0.3.2 and never invokes GNU Make or recipe commands. +Supported checks are parser-backed Makefile rules and configured static +limits. Variable intent, `$`/`$$` behavior, parallelism, order-only +prerequisites, recipe side effects, and domain behavior are unsupported. diff --git a/.github/skills/internal-makefile/agents/openai.yaml b/.github/skills/internal-makefile/agents/openai.yaml index d5d49a5b..b3799027 100644 --- a/.github/skills/internal-makefile/agents/openai.yaml +++ b/.github/skills/internal-makefile/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Internal Makefile" - short_description: "Makefile targets and recipes" - default_prompt: "Use $internal-makefile for Makefile or .mk target, recipe, and validation changes." + short_description: "Strict Makefile format handling" + default_prompt: "Use $internal-makefile when editing or reviewing Make targets, prerequisites, recipe prefixes, .PHONY declarations, variables, or static format checks." diff --git a/.github/skills/internal-makefile/fixtures/invalid/missing-phony.mk b/.github/skills/internal-makefile/fixtures/invalid/missing-phony.mk new file mode 100644 index 00000000..7e8c27ea --- /dev/null +++ b/.github/skills/internal-makefile/fixtures/invalid/missing-phony.mk @@ -0,0 +1,2 @@ +all: + @printf 'not a file target\\n' diff --git a/.github/skills/internal-makefile/fixtures/valid/Makefile b/.github/skills/internal-makefile/fixtures/valid/Makefile new file mode 100644 index 00000000..a9cf303d --- /dev/null +++ b/.github/skills/internal-makefile/fixtures/valid/Makefile @@ -0,0 +1,11 @@ +.PHONY: all build clean test + +all: build + +build: + @printf 'building %s\\n' "$$PWD" + +clean: + @rm -f output.txt + +test: all diff --git a/.github/skills/internal-makefile/references/validation-contract.md b/.github/skills/internal-makefile/references/validation-contract.md new file mode 100644 index 00000000..f100a8b4 --- /dev/null +++ b/.github/skills/internal-makefile/references/validation-contract.md @@ -0,0 +1,20 @@ +# Makefile validation contract + +The bundle checker accepts explicit Makefile or `.mk` paths and runs +`checkmake` 0.3.2 with the bundled configuration. Install the pinned tool +without changing the repository: + +```bash +go install github.com/checkmake/checkmake/cmd/checkmake@v0.3.2 +``` + +The checker is read-only, emits at most 100 findings, and returns `0` when +checks passed within supported scope, `1` when the tool reports findings, and +`2` for usage, dependency, file, or internal failures. It supports +`--self-test` for the bundled fixtures and never invokes GNU Make or recipes. + +At `checkmake` 0.3.2 the bundle uses the parser and Make-specific rule +families exposed by the tool, including `phonydeclared`, while configuring +`maxbodylength` to 100. The wrapper does not claim to validate `$`/`$$` intent, +parallelism, order-only prerequisites, recipe side effects, recursive Make, +or domain behavior; those remain human review concerns. diff --git a/.github/skills/internal-makefile/scripts/check.sh b/.github/skills/internal-makefile/scripts/check.sh new file mode 100755 index 00000000..640b455e --- /dev/null +++ b/.github/skills/internal-makefile/scripts/check.sh @@ -0,0 +1,109 @@ +#!/bin/bash +set -u + +script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)" +required_version="checkmake version 0.3.2" +max_findings=100 + +usage() { + printf 'usage: %s [--self-test | FILE [FILE ...]]\n' "$(basename "$0")" >&2 +} + +require_checkmake() { + if ! command -v checkmake >/dev/null 2>&1; then + printf 'error: required %s is missing; install with: go install github.com/checkmake/checkmake/cmd/checkmake@v0.3.2\n' \ + "$required_version" >&2 + return 2 + fi + + local version_output + version_output="$(checkmake --version 2>&1)" + local detected_version="" + if [[ "$version_output" =~ ^checkmake([[:space:]]+version)?[[:space:]]+([^[:space:]]+) ]]; then + detected_version="${BASH_REMATCH[2]}" + fi + if [[ "$detected_version" != "0.3.2" ]]; then + printf 'error: required %s, found: %s\n' "$required_version" "$version_output" >&2 + printf 'install with: go install github.com/checkmake/checkmake/cmd/checkmake@v0.3.2\n' >&2 + return 2 + fi +} + +validate_files() { + local file + for file in "$@"; do + if [[ ! -f "$file" ]]; then + printf 'error: input file not found: %s\n' "$file" >&2 + return 2 + fi + done +} + +run_checker() { + local output_file rc + output_file="$(mktemp "${TMPDIR:-/tmp}/internal-makefile.XXXXXX")" || { + printf 'error: unable to create temporary output file\n' >&2 + return 2 + } + + checkmake \ + --config "${script_dir}/checkmake.ini" \ + --output text \ + "$@" >"$output_file" 2>&1 + rc=$? + sed -n "1,${max_findings}p" "$output_file" + rm -f "$output_file" + + case "$rc" in + 0) return 0 ;; + 1) return 1 ;; + *) + printf 'error: checkmake exited with status %s\n' "$rc" >&2 + return 2 + ;; + esac +} + +self_test() { + local valid invalid rc + valid="${script_dir}/../fixtures/valid/Makefile" + invalid="${script_dir}/../fixtures/invalid/missing-phony.mk" + + run_checker "$valid" + rc=$? + if [[ "$rc" -ne 0 ]]; then + printf 'error: Makefile self-test valid fixture returned %s\n' "$rc" >&2 + return 2 + fi + + run_checker "$invalid" + rc=$? + if [[ "$rc" -ne 1 ]]; then + printf 'error: Makefile self-test invalid fixture returned %s\n' "$rc" >&2 + return 2 + fi + + printf 'Makefile self-test passed\n' + return 0 +} + +if [[ "${1:-}" == "--self-test" ]]; then + if [[ "$#" -ne 1 ]]; then + usage + exit 2 + fi + require_checkmake || exit $? + self_test + exit $? +fi + +if [[ "$#" -eq 0 ]]; then + printf 'error: at least one input file is required\n' >&2 + usage + exit 2 +fi + +require_checkmake || exit $? +validate_files "$@" || exit $? +run_checker "$@" +exit $? diff --git a/.github/skills/internal-makefile/scripts/checkmake.ini b/.github/skills/internal-makefile/scripts/checkmake.ini new file mode 100644 index 00000000..2d7efdba --- /dev/null +++ b/.github/skills/internal-makefile/scripts/checkmake.ini @@ -0,0 +1,2 @@ +[maxbodylength] +maxBodyLength = 100 diff --git a/.github/skills/internal-markdown/SKILL.md b/.github/skills/internal-markdown/SKILL.md index 9ec0a7a3..c984f95e 100644 --- a/.github/skills/internal-markdown/SKILL.md +++ b/.github/skills/internal-markdown/SKILL.md @@ -1,37 +1,42 @@ --- name: internal-markdown -description: Use when editing repository-owned Markdown that needs concise structure, explicit paths, links, and maintainable prose. +description: Use when editing or reviewing Markdown structure, fences, references, links, paths, or dialect-aware format checks. --- # Internal Markdown -## Referenced skills - -- None. - ## When to use -- Repository-owned Markdown documentation, prompts, skills, agents, plans, and governance prose. -- Reviews focused on heading hierarchy, concise sections, path formatting, local links, and stale examples. -- Markdown edits without a narrower owner such as retained-plan, skill-authoring, or agent-authoring rules. +- Markdown edits where generic structure and link safety are the active concern. +- Reviews focused on heading fragments, fenced code blocks, local paths, + inline links, reference definitions, and dialect awareness. +- Format-owner routing when a document has a narrower operational owner. ## When not to use -- README files unless the user explicitly authorizes the README change. -- Deep skill-reference rewrites that change bundle boundaries; use the skill-authoring owner first. -- Imported upstream Markdown that must remain verbatim unless the task explicitly allows a fork or refresh. +- Imported Markdown that must remain verbatim unless explicitly allowed. +- A domain-specific document whose semantics are owned by another skill or + instruction set. +- Editorial, audience, or policy review beyond Markdown structure and links. ## Baseline -- Use Plain Technical English for repository-owned prose. -- Prefer task-oriented sections and concise bullets over long narrative blocks. -- Use backticks for commands, paths, identifiers, schema fields, and literal values. -- Keep links explicit and maintainable. -- Preserve required technical names unchanged. -- Update docs when behavior or workflow contracts change. +- Preserve fenced-code contents and choose a dialect before judging extensions. +- Keep local paths and link destinations explicit and maintainable. +- Check heading fragments, reference definitions, and link structure without + treating valid Markdown as a prose-quality verdict. ## Validation -- Run the closest Markdown lint or repository documentation check when available. -- Re-check local links when moving or deleting Markdown assets. -- For generated documentation, run the generator instead of editing output by hand. +Run the bundle-owned checker with explicit files: + +```bash +.github/skills/internal-markdown/scripts/check.sh FILE [FILE ...] +``` + +The checker returns `0` when checks passed within supported scope, `1` for +format findings, and `2` for usage, dependency, file, or internal failures. +It requires `markdownlint-cli2` 0.22.1 and does not install dependencies. +Supported checks are selected structural link and reference rules. Dialect +choice, external or local filesystem availability, editorial quality, and +heading policy are unsupported and remain review-only. diff --git a/.github/skills/internal-markdown/agents/openai.yaml b/.github/skills/internal-markdown/agents/openai.yaml index 707178fb..6b191479 100644 --- a/.github/skills/internal-markdown/agents/openai.yaml +++ b/.github/skills/internal-markdown/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Internal Markdown" - short_description: "Markdown structure and prose" - default_prompt: "Use $internal-markdown for repository-owned Markdown structure, links, paths, and prose." + short_description: "Strict Markdown format handling" + default_prompt: "Use $internal-markdown when editing or reviewing Markdown structure, fences, references, paths, links, or dialect-aware format checks." diff --git a/.github/skills/internal-markdown/fixtures/invalid/broken-references.md b/.github/skills/internal-markdown/fixtures/invalid/broken-references.md new file mode 100644 index 00000000..4d61c6b6 --- /dev/null +++ b/.github/skills/internal-markdown/fixtures/invalid/broken-references.md @@ -0,0 +1,12 @@ +# Broken references + +[reversed] (https://example.com) + +[undefined][missing] + +[fragment](#missing-heading) + +[]() + +[project]: https://example.com/one +[project]: https://example.com/two diff --git a/.github/skills/internal-markdown/fixtures/valid/document.md b/.github/skills/internal-markdown/fixtures/valid/document.md new file mode 100644 index 00000000..40bf7015 --- /dev/null +++ b/.github/skills/internal-markdown/fixtures/valid/document.md @@ -0,0 +1,11 @@ +# Format example + +This document has a [local section](#details) and a [reference link][project]. + +## Details + +```text +[code is not a link](#not-a-real-target) +``` + +[project]: https://example.com/project diff --git a/.github/skills/internal-markdown/references/validation-contract.md b/.github/skills/internal-markdown/references/validation-contract.md new file mode 100644 index 00000000..daf959ad --- /dev/null +++ b/.github/skills/internal-markdown/references/validation-contract.md @@ -0,0 +1,20 @@ +# Markdown validation contract + +The bundle checker accepts explicit Markdown files and feeds each file through +standard input to `markdownlint-cli2` 0.22.1 with the bundled configuration. +Install the pinned tool without changing the repository: + +```bash +npm install -g markdownlint-cli2@0.22.1 +``` + +The checker is read-only, processes at most 100 explicit files, bounds output +to 100 findings per file, and returns `0` when checks passed within supported +scope, `1` for format findings, and `2` for usage, dependency, file, or +internal failures. It supports `--self-test` for the bundled fixtures. + +Supported rules are reversed links (`MD011`), empty links (`MD042`), invalid +local fragments (`MD051`), undefined references (`MD052`), and duplicate +reference definitions (`MD053`). Markdown remains permissive: dialect choice, +external or local filesystem targets, editorial quality, and heading policy +are review-only and are not validated by this bundle. diff --git a/.github/skills/internal-markdown/scripts/check.sh b/.github/skills/internal-markdown/scripts/check.sh new file mode 100755 index 00000000..a3eee955 --- /dev/null +++ b/.github/skills/internal-markdown/scripts/check.sh @@ -0,0 +1,138 @@ +#!/bin/bash +set -u + +script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)" +required_version="markdownlint-cli2 v0.22.1" +max_findings=100 +max_files=100 + +usage() { + printf 'usage: %s [--self-test | FILE [FILE ...]]\n' "$(basename "$0")" >&2 +} + +require_markdownlint() { + if ! command -v markdownlint-cli2 >/dev/null 2>&1; then + printf 'error: required %s is missing; install with: npm install -g markdownlint-cli2@0.22.1\n' \ + "$required_version" >&2 + return 2 + fi + + local version_output + version_output="$(markdownlint-cli2 --version 2>&1)" + local detected_version="" + if [[ "$version_output" =~ ^markdownlint-cli2[[:space:]]+v([^[:space:]]+) ]]; then + detected_version="${BASH_REMATCH[1]}" + fi + if [[ "$detected_version" != "0.22.1" ]]; then + printf 'error: required %s, found: %s\n' "$required_version" "$version_output" >&2 + printf 'install with: npm install -g markdownlint-cli2@0.22.1\n' >&2 + return 2 + fi +} + +validate_files() { + local file + for file in "$@"; do + if [[ ! -f "$file" ]]; then + printf 'error: input file not found: %s\n' "$file" >&2 + return 2 + fi + done +} + +run_file() { + local file="$1" + local output_file rc + output_file="$(mktemp "${TMPDIR:-/tmp}/internal-markdown.XXXXXX")" || { + printf 'error: unable to create temporary output file\n' >&2 + return 2 + } + + markdownlint-cli2 \ + --config "${script_dir}/markdownlint-cli2.jsonc" \ + - < "$file" >"$output_file" 2>&1 + rc=$? + local line line_count=0 + while IFS= read -r line && [[ "$line_count" -lt "$max_findings" ]]; do + line_count=$((line_count + 1)) + case "$line" in + stdin:*) printf '%s:%s\n' "$file" "${line#stdin:}" ;; + *) printf '%s: %s\n' "$file" "$line" ;; + esac + done < "$output_file" + rm -f "$output_file" + + case "$rc" in + 0) return 0 ;; + 1) return 1 ;; + *) + printf 'error: markdownlint-cli2 exited with status %s for %s\n' "$rc" "$file" >&2 + return 2 + ;; + esac +} + +run_files() { + local finding=0 rc + local file + for file in "$@"; do + run_file "$file" + rc=$? + case "$rc" in + 0) ;; + 1) finding=1 ;; + *) return 2 ;; + esac + done + return "$finding" +} + +self_test() { + local valid invalid rc + valid="${script_dir}/../fixtures/valid/document.md" + invalid="${script_dir}/../fixtures/invalid/broken-references.md" + + run_files "$valid" + rc=$? + if [[ "$rc" -ne 0 ]]; then + printf 'error: Markdown self-test valid fixture returned %s\n' "$rc" >&2 + return 2 + fi + + run_files "$invalid" + rc=$? + if [[ "$rc" -ne 1 ]]; then + printf 'error: Markdown self-test invalid fixture returned %s\n' "$rc" >&2 + return 2 + fi + + printf 'Markdown self-test passed\n' + return 0 +} + +if [[ "${1:-}" == "--self-test" ]]; then + if [[ "$#" -ne 1 ]]; then + usage + exit 2 + fi + require_markdownlint || exit $? + self_test + exit $? +fi + +if [[ "$#" -eq 0 ]]; then + printf 'error: at least one input file is required\n' >&2 + usage + exit 2 +fi + +if [[ "$#" -gt "$max_files" ]]; then + printf 'error: at most %s input files are supported; received %s\n' \ + "$max_files" "$#" >&2 + exit 2 +fi + +require_markdownlint || exit $? +validate_files "$@" || exit $? +run_files "$@" +exit $? diff --git a/.github/skills/internal-markdown/scripts/markdownlint-cli2.jsonc b/.github/skills/internal-markdown/scripts/markdownlint-cli2.jsonc new file mode 100644 index 00000000..0edff7d9 --- /dev/null +++ b/.github/skills/internal-markdown/scripts/markdownlint-cli2.jsonc @@ -0,0 +1,12 @@ +{ + "noBanner": true, + "noProgress": true, + "config": { + "default": false, + "MD011": true, + "MD042": true, + "MD051": true, + "MD052": true, + "MD053": true + } +} diff --git a/.github/skills/internal-python-project/SKILL.md b/.github/skills/internal-python-project/SKILL.md index 74d288ec..08ebdd76 100644 --- a/.github/skills/internal-python-project/SKILL.md +++ b/.github/skills/internal-python-project/SKILL.md @@ -1,6 +1,6 @@ --- name: internal-python-project -description: Use when creating or modifying Python package or application code whose primary contract is imported behavior, service boundaries, or framework-owned flows rather than operator-facing scripts. +description: Use when creating, modifying, or reviewing importable Python package, library, application, service, or framework behavior rather than directly executed operator tooling. --- # Python Project Skill @@ -26,6 +26,9 @@ description: Use when creating or modifying Python package or application code w - This skill covers structured package, library, or application components whose primary contract is reusable domain, service, or framework behavior. - Small operator-facing tools remain out of scope even when they have multiple files or tests. - A `lib/` folder, root-level tests, or multiple entrypoints alone do not make a tool application code. +- A thin CLI adapter remains project-owned when the primary contract is + importable behavior; route direct-execution tooling to + `internal-python-script`. ## Compact Python baseline @@ -38,7 +41,7 @@ description: Use when creating or modifying Python package or application code w - Pass configuration into reusable project code through typed settings, constructor arguments, or function parameters. Domain and service code should not read environment variables, files, or deployment defaults directly unless that boundary is its explicit responsibility. - Do not confuse domain invariants with configuration. Stable rules that belong to the domain may stay near the domain code; deployment-specific paths, endpoints, thresholds, defaults, and feature switches should live at the configuration boundary. - Do not vendor libraries, wheelhouses, copied site-packages, or fallback dependency mirrors. -- If external packages are introduced, keep exact pins and hashes in the owning requirements file. +- Preserve the repository-declared dependency manager. For pip requirements, keep exact pins and hashes in the owning requirements file; for another declared dependency manager, update its canonical lock artifact and use its frozen or locked validation command. ## Application-specific guidance @@ -85,6 +88,6 @@ Load `references/common-mistakes.md` for the full mistake table. ## Validation - `python -m compileall ` (syntax check) -- `pip install --require-hashes -r requirements.txt` (dependency integrity check, only when requirements change) +- For pip-managed projects, run `pip install --require-hashes -r requirements.txt` when requirements change; for another declared manager, run its canonical frozen or locked validation command. - `pytest tests/` (run tests) - Lint with project's configured linter. diff --git a/.github/skills/internal-python-project/agents/openai.yaml b/.github/skills/internal-python-project/agents/openai.yaml index 0a4e3841..cd903353 100644 --- a/.github/skills/internal-python-project/agents/openai.yaml +++ b/.github/skills/internal-python-project/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Internal Project Python" - short_description: "Help with Internal Project Python tasks" - default_prompt: "Use $internal-python-project for this task and follow the repository-owned workflow in the skill." + short_description: "Importable Python application guidance" + default_prompt: "Use $internal-python-project for importable Python package, library, application, service, or framework behavior; route directly executed operator tooling to $internal-python-script." diff --git a/.github/skills/internal-python-project/references/common-mistakes.md b/.github/skills/internal-python-project/references/common-mistakes.md index 3b2f8ada..e73c6166 100644 --- a/.github/skills/internal-python-project/references/common-mistakes.md +++ b/.github/skills/internal-python-project/references/common-mistakes.md @@ -4,11 +4,12 @@ | --- | --- | --- | | Business logic mixed with I/O (DB calls, HTTP) | Untestable, hard to refactor | Extract pure logic into service/domain modules | | Mutable default arguments (`def f(items=[])`) | Shared state between calls — classic Python gotcha | Use `None` default + create inside function | -| Bare `except:` or `except Exception:` | Swallows `KeyboardInterrupt`, `SystemExit` | Catch specific exceptions | +| bare `except:` | Also catches control-flow exceptions such as `KeyboardInterrupt` and `SystemExit` | Catch the narrowest expected exception | +| Broad `except Exception` without handling, logging, or re-raise | Can hide ordinary application failures and leave partial work unexplained | Handle expected failures explicitly and let unexpected failures propagate | | No type hints on public API | Hard to understand contracts, no static analysis | Add type hints on function signatures | | Injecting every collaborator as a `*_fn` hook or alias shim | Hides real seams and makes call flow harder to follow | Inject only true external boundaries or variability points; call stable helpers directly | | Copying shared helper logic across modules | Fixes drift and behavior diverges across call sites | Define the helper once in the owning module and import it | -| Updating dependency requirements without refreshed hashes | Reproducible installs break or drift silently | Regenerate exact pins and hashes, then validate with `pip install --require-hashes -r requirements.txt` | +| Changing dependencies without updating the declared manager's lock artifact | Reproducible installs break or drift silently | Preserve the declared dependency manager; for pip, regenerate exact pins and hashes, and otherwise use its canonical frozen or locked validation command | | Tests that depend on execution order | Fragile test suite, non-deterministic failures | Each test must be self-contained | | Forcing async into CPU-bound or simple flows | Adds complexity without throughput benefit | Keep it synchronous unless I/O concurrency is the real bottleneck | | HTTP client pools smaller than worker or task concurrency | Work queues behind the pool and hides throughput bottlenecks | Size connection pools and limits to match max worker or async concurrency | diff --git a/.github/skills/internal-python-project/references/examples.md b/.github/skills/internal-python-project/references/examples.md index 26074c0b..0a709568 100644 --- a/.github/skills/internal-python-project/references/examples.md +++ b/.github/skills/internal-python-project/references/examples.md @@ -2,6 +2,8 @@ ## Minimal Module Example +`account_status.py` + ```python """Purpose: Resolve account status based on domain rules.""" @@ -26,6 +28,8 @@ def resolve_account_state(account_id: AccountId, is_locked: bool) -> str: ## Minimal Test Example ```python +from account_status import AccountId + import pytest diff --git a/.github/skills/internal-python-script/SKILL.md b/.github/skills/internal-python-script/SKILL.md index 3243203b..09565347 100644 --- a/.github/skills/internal-python-script/SKILL.md +++ b/.github/skills/internal-python-script/SKILL.md @@ -1,6 +1,6 @@ --- name: internal-python-script -description: Use when creating or modifying standalone Python scripts, CLIs, or small operator-facing toolkits whose primary contract is direct execution rather than reusable package or application code. +description: Use when creating, modifying, or reviewing directly executed Python scripts, CLIs, automation, or small operator-facing toolkits rather than importable application behavior. --- # Python Script Skill @@ -25,7 +25,9 @@ description: Use when creating or modifying standalone Python scripts, CLIs, or - This skill covers standalone operational tools, CLI entrypoints, and small script toolkits whose primary contract is direct execution. - A tool does not become application code just because it has multiple files, a `lib/` folder, or root-level tests. -- Move out of this lane only when the primary contract becomes imported behavior, service boundaries, or framework-owned flows. +- Move out of this lane only when the primary contract becomes imported behavior, + service boundaries, or framework-owned flows; route those cases to + `internal-python-project`. ## Script-specific guidance @@ -35,14 +37,13 @@ description: Use when creating or modifying standalone Python scripts, CLIs, or - Name configuration values by purpose, not by type: paths, file names, field lists, thresholds, defaults, mappings, filters, and output modes should explain what behavior they control. - Do not hide script-specific configuration inside helper modules or libraries. Helpers should accept explicit parameters or a small typed settings object when several values travel together. - Keep single-file scripts under 400 lines when possible. At 300 lines, review whether orchestration and helper boundaries stay clear; at 400 lines, split-or-justify is required. -- Place shared helper logic in local helper modules, preferably under `utils/` when the toolkit structure supports that layout. +- Place shared helper logic in local helper modules, preferably under `lib/` when the toolkit structure supports that layout. - For operator-facing script work, crossing the 400-line threshold should move toward a toolkit or project structure according to the primary contract, not an ever-growing single entrypoint. - Keep policy checks focused on maintained source; generated outputs and large fixture data are excluded unless directly edited. - Prefer `argparse`, `pathlib.Path`, and small helper functions for operator-facing tools. - Keep operator-facing console reporting centralized in a dedicated reporter, for example `ExecutionReporter`. Application logic should call semantic reporter methods instead of constructing styled strings or scattered `print()` calls. - Use `rich` as the preferred console rendering library for polished human-facing CLI reports when the terminal experience is part of the contract. Keep it out of `--format json`, other machine-readable outputs, and reusable helper logic. - Keep emoji, panels, tables, and color at human-facing boundaries such as banners, sections, success, warning, error, and summaries. Keep reusable helpers and machine-readable output paths free of decorative log formatting. -- Load `references/reporting.md` when a script needs professional console reporting, `rich` rendering, an `ExecutionReporter` shape, redaction rules, or verbose/debug output boundaries. - When a tool can be called from subdirectories, resolve the repository root explicitly instead of assuming the current working directory. - Use type hints on non-trivial public helpers and CLI-facing boundaries. - Use `asyncio` only when the script truly coordinates multiple I/O-bound tasks. @@ -60,9 +61,18 @@ description: Use when creating or modifying standalone Python scripts, CLIs, or - Keep comments, docstrings, logs, exceptions, and CLI output in English. - Use the repository-declared runtime before falling back to ambient `python3`. - Do not vendor libraries, wheelhouses, copied site-packages, or fallback dependency mirrors. -- If external packages are introduced, keep exact pins and hashes in the owning requirements file. +- Keep dependency changes in the repository-declared dependency manager and its canonical lock artifact. -## Dependency decision note +## Dependency policy + +Preserve the repository-declared dependency manager. For pip requirements, keep +exact pins and hashes in the owning requirements file. For another declared +dependency manager, update its canonical lock artifact and use its frozen or +locked validation command. + +For pip requirements, generate the lock output with +`pip-compile --generate-hashes` and validate it with +`pip install --require-hashes -r requirements.txt`. When the Python baseline requires a dependency decision note, keep it short, for example: @@ -75,21 +85,21 @@ Dependency decision note - Keep the note short and task-specific. - Compare the standard library with realistic third-party candidates. -- If the final choice uses external libraries, create or update the local `requirements.txt` before finishing the task. -- Keep exact pins and current hashes in `requirements.txt`. Use `pip-compile --generate-hashes` or an equivalent repository-approved workflow, then validate with `pip install --require-hashes -r requirements.txt` when the requirements file changes. -- If several entrypoints share the same lock file, record the decision once at the shared toolkit `requirements.txt` rather than repeating it in every script. +- If the final choice uses external libraries and no other dependency manager is declared, create or update the local `requirements.txt` before finishing the task; otherwise update the declared manager's canonical lock artifact. +- If several entrypoints share the same pip lock file, record the decision once at the shared toolkit `requirements.txt` rather than repeating it in every script. ## Layout and templates -Load `references/layout-and-templates.md` when you need the default folder layout, a repo-aligned multi-tool toolkit layout, a minimal entry point, a hash-locked `requirements.txt`, or the launcher pattern. +Load `references/layout-and-templates.md` when you need the default folder layout, a repo-aligned multi-tool toolkit layout, a minimal entry point, a pip-managed hash-locked `requirements.txt`, or the launcher pattern. -Load `references/reporting.md` when the script needs a richer `ExecutionReporter`, `rich` console rendering, status tables, redaction behavior, or a final operator summary. +Load `references/reporting.md` when the script needs polished human-facing +output, `rich` rendering, status tables, redaction, verbose diagnostics, or a +final operator summary. Keep these rules visible while drafting: - Use a dedicated tool folder or toolkit root rather than a loose top-level `.py` file. -- Add `requirements.txt` and `run.sh` only when external packages are actually needed. -- Generate `requirements.txt` with `pip-compile --generate-hashes` or an equivalent locked workflow. +- Add a pip-managed `requirements.txt` and `run.sh` only when external packages are actually needed and no other dependency manager is declared. - Reuse an existing shared runner such as `.github/scripts/run.sh` instead of cloning bootstrap logic into every entrypoint. - Mirror script or toolkit coverage under the repository-root `tests/` tree; do not create ad-hoc test folders beside the tool. @@ -117,6 +127,6 @@ Load `references/common-mistakes.md` for the full mistake table. - `python -m py_compile .py` (syntax check) - `bash -n run.sh` (launcher syntax check, only when `run.sh` exists) -- `pip install --require-hashes -r requirements.txt` (dependency integrity check, only when requirements change) +- For pip-managed tools, run `pip install --require-hashes -r requirements.txt` when requirements change; for another declared manager, run its canonical frozen or locked validation command. - `pytest tests/` (run tests) - `python -m compileall ` or the repository's canonical shared runner when the tool already lives inside a maintained toolkit diff --git a/.github/skills/internal-python-script/agents/openai.yaml b/.github/skills/internal-python-script/agents/openai.yaml index 0bd3356c..f5147479 100644 --- a/.github/skills/internal-python-script/agents/openai.yaml +++ b/.github/skills/internal-python-script/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Internal Script Python" - short_description: "Help with Internal Script Python tasks" - default_prompt: "Use $internal-python-script for this task and follow the repository-owned workflow in the skill." + short_description: "Direct-execution Python tooling" + default_prompt: "Use $internal-python-script for directly executed Python scripts, CLIs, automation, or operator-facing toolkits; route importable application behavior to $internal-python-project." diff --git a/.github/skills/internal-python-script/references/common-mistakes.md b/.github/skills/internal-python-script/references/common-mistakes.md index b9a2080a..3273329e 100644 --- a/.github/skills/internal-python-script/references/common-mistakes.md +++ b/.github/skills/internal-python-script/references/common-mistakes.md @@ -5,14 +5,15 @@ | Missing `if __name__ == "__main__":` guard | Script runs on import, breaks testing and reuse | Always guard the entry point | | Using a hyphenated or file-only entrypoint that cannot be imported cleanly | Breaks `python -m`, packaging, and test reuse | Expose an importable `cli.py`, package `__main__.py`, or `console_scripts` entrypoint | | Using `print()` for errors | Errors go to stdout, mixed with normal output | Use `print(..., file=sys.stderr)` or `logging` | -| Bare `except:` or `except Exception:` at top level | Swallows all errors including KeyboardInterrupt | Catch specific exceptions; let unexpected ones propagate | +| bare `except:` at the script boundary | Also catches control-flow exceptions such as `KeyboardInterrupt` and `SystemExit` | Catch the narrowest expected exception and let control-flow exceptions propagate | +| Broad `except Exception` without handling, logging, or re-raise | Can hide ordinary application failures and leave partial work unexplained | Handle expected failures explicitly and let unexpected failures propagate | | Hardcoded file paths | Non-portable across machines | Use `argparse`, `pathlib`, or environment variables | | No argument parsing | Caller has to modify script source to change behavior | Use `argparse` for any configurable parameter | -| Installing deps globally or without hash-locked version pinning | Non-reproducible environment and hidden setup drift | Keep dependencies in the local `requirements.txt` with exact pins and hashes | +| Installing deps outside the declared dependency manager or without a reproducible lock | Non-reproducible environment and hidden setup drift | Preserve the declared manager; for pip use exact pins and hashes, otherwise use its canonical lock artifact | | Adding an empty `requirements.txt` to a stdlib-only tool | Adds noise and implies missing setup steps | Omit `requirements.txt` when the script uses only the standard library | -| Updating `requirements.txt` without refreshed hashes | Breaks reproducible installs and hides dependency drift | Regenerate exact pins and hashes, then validate with `pip install --require-hashes -r requirements.txt` | +| Changing dependencies without updating the declared manager's lock artifact | Breaks reproducible installs and hides dependency drift | Preserve the declared manager; for pip regenerate exact pins and hashes, otherwise run its frozen or locked validation command | | Wrapping a stdlib-only script in Bash | Adds setup indirection without solving a real dependency problem | Document direct `python3