From cc427f2cf909246023c32bd81cda074d3f523560 Mon Sep 17 00:00:00 2001 From: zawakin Date: Sun, 8 Feb 2026 12:25:19 +0900 Subject: [PATCH 1/4] chore: add .claude/settings.json with broad permission allowlist Co-Authored-By: Claude Opus 4.6 --- .claude/settings.json | 120 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 .claude/settings.json diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..92dabf1 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,120 @@ +{ + "env": { + "BASH_DEFAULT_TIMEOUT_MS": "180000", + "CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "1" + }, + "permissions": { + "allow": [ + "Bash(chmod:*)", + "Bash(cp:*)", + "Bash(cat:*)", + "Bash(date:*)", + "Bash(echo:*)", + "Bash(env)", + "Bash(fd:*)", + "Bash(find:*)", + "Bash(grep:*)", + "Bash(head:*)", + "Bash(jq:*)", + "Bash(ln:*)", + "Bash(ls:*)", + "Bash(mkdir:*)", + "Bash(mv:*)", + "Bash(pwd)", + "Bash(rm:*)", + "Bash(sed:*)", + "Bash(sort:*)", + "Bash(tail:*)", + "Bash(tee:*)", + "Bash(test:*)", + "Bash(touch:*)", + "Bash(tree:*)", + "Bash(tree2md:*)", + "Bash(wc:*)", + "Bash(which:*)", + "Bash(whoami)", + "Bash(xargs:*)", + "Bash(awk:*)", + "Bash(curl:*)", + "Bash(wget:*)", + "Bash(cargo build:*)", + "Bash(cargo check:*)", + "Bash(cargo clippy:*)", + "Bash(cargo fmt:*)", + "Bash(cargo insta:*)", + "Bash(cargo release:*)", + "Bash(cargo run:*)", + "Bash(cargo test:*)", + "Bash(rustup:*)", + "Bash(git add:*)", + "Bash(git apply:*)", + "Bash(git bisect:*)", + "Bash(git blame:*)", + "Bash(git branch:*)", + "Bash(git check-ignore:*)", + "Bash(git checkout:*)", + "Bash(git cherry-pick:*)", + "Bash(git clean:*)", + "Bash(git cliff:*)", + "Bash(git clone:*)", + "Bash(git commit:*)", + "Bash(git config --get:*)", + "Bash(git describe:*)", + "Bash(git diff:*)", + "Bash(git fetch:*)", + "Bash(git log:*)", + "Bash(git ls-files:*)", + "Bash(git ls-remote:*)", + "Bash(git ls-tree:*)", + "Bash(git merge:*)", + "Bash(git mv:*)", + "Bash(git pull:*)", + "Bash(git push:*)", + "Bash(git rebase:*)", + "Bash(git reset:*)", + "Bash(git restore:*)", + "Bash(git rev-parse:*)", + "Bash(git revert:*)", + "Bash(git rm:*)", + "Bash(git show:*)", + "Bash(git stash:*)", + "Bash(git status:*)", + "Bash(git switch:*)", + "Bash(git tag:*)", + "Bash(gw:*)", + "Bash(gh api:*)", + "Bash(gh issue view:*)", + "Bash(gh pr checkout:*)", + "Bash(gh pr checks:*)", + "Bash(gh pr close:*)", + "Bash(gh pr comment:*)", + "Bash(gh pr create:*)", + "Bash(gh pr diff:*)", + "Bash(gh pr edit:*)", + "Bash(gh pr list:*)", + "Bash(gh pr view:*)", + "Bash(gh release list:*)", + "Bash(gh release view:*)", + "Bash(gh run list:*)", + "Bash(gh run view:*)", + "Bash(gh run watch:*)", + "Bash(gh secret list:*)", + "Bash(mise install:*)", + "Bash(mise list:*)", + "Bash(mise run:*)", + "Bash(mise task:*)", + "Bash(mise tasks:*)", + "Bash(rg:*)", + "Bash(typos:*)", + "Bash(./target/release/agtrace:*)", + "Bash(./target/debug/agtrace:*)", + "Edit(.claude/**)", + "Read(.claude/**)", + "Write(.claude/**)", + "WebFetch(domain:*)", + "WebSearch", + "mcp__o3__o3-search" + ], + "deny": [] + } +} From cfde244b16354d9682b8bd89d21d51c1e283e5a3 Mon Sep 17 00:00:00 2001 From: zawakin Date: Sun, 8 Feb 2026 12:26:26 +0900 Subject: [PATCH 2/4] chore: remove execplan skill Co-Authored-By: Claude Opus 4.6 --- .claude/skills/execplan/SKILL.md | 157 ------------------------------- CLAUDE.md | 2 - 2 files changed, 159 deletions(-) delete mode 100644 .claude/skills/execplan/SKILL.md diff --git a/.claude/skills/execplan/SKILL.md b/.claude/skills/execplan/SKILL.md deleted file mode 100644 index 5748c37..0000000 --- a/.claude/skills/execplan/SKILL.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -name: execplan -description: ExecPlan expert - Helps create and maintain execution plans following PLANS.md guidelines. Automatically activates for complex features or significant refactors. ---- - -# Execution Plans (ExecPlans): - -This document describes the requirements for an execution plan ("ExecPlan"), a design document that a coding agent can follow to deliver a working feature or system change. Treat the reader as a complete beginner to this repository: they have only the current working tree and the single ExecPlan file you provide. There is no memory of prior plans and no external context. - -## How to use ExecPlans and PLANS.md - -When authoring an executable specification (ExecPlan), follow PLANS.md _to the letter_. If it is not in your context, refresh your memory by reading the entire PLANS.md file. Be thorough in reading (and re-reading) source material to produce an accurate specification. When creating a spec, start from the skeleton and flesh it out as you do your research. - -When implementing an executable specification (ExecPlan), do not prompt the user for "next steps"; simply proceed to the next milestone. Keep all sections up to date, add or split entries in the list at every stopping point to affirmatively state the progress made and next steps. Resolve ambiguities autonomously, and commit frequently. - -When discussing an executable specification (ExecPlan), record decisions in a log in the spec for posterity; it should be unambiguously clear why any change to the specification was made. ExecPlans are living documents, and it should always be possible to restart from _only_ the ExecPlan and no other work. - -When researching a design with challenging requirements or significant unknowns, use milestones to implement proof of concepts, "toy implementations", etc., that allow validating whether the user's proposal is feasible. Read the source code of libraries by finding or acquiring them, research deeply, and include prototypes to guide a fuller implementation. - -## Requirements - -NON-NEGOTIABLE REQUIREMENTS: - -* Every ExecPlan must be fully self-contained. Self-contained means that in its current form it contains all knowledge and instructions needed for a novice to succeed. -* Every ExecPlan is a living document. Contributors are required to revise it as progress is made, as discoveries occur, and as design decisions are finalized. Each revision must remain fully self-contained. -* Every ExecPlan must enable a complete novice to implement the feature end-to-end without prior knowledge of this repo. -* Every ExecPlan must produce a demonstrably working behavior, not merely code changes to "meet a definition". -* Every ExecPlan must define every term of art in plain language or do not use it. - -Purpose and intent come first. Begin by explaining, in a few sentences, why the work matters from a user's perspective: what someone can do after this change that they could not do before, and how to see it working. Then guide the reader through the exact steps to achieve that outcome, including what to edit, what to run, and what they should observe. - -The agent executing your plan can list files, read files, search, run the project, and run tests. It does not know any prior context and cannot infer what you meant from earlier milestones. Repeat any assumption you rely on. Do not point to external blogs or docs; if knowledge is required, embed it in the plan itself in your own words. If an ExecPlan builds upon a prior ExecPlan and that file is checked in, incorporate it by reference. If it is not, you must include all relevant context from that plan. - -## Formatting - -Format and envelope are simple and strict. Each ExecPlan must be one single fenced code block labeled as `md` that begins and ends with triple backticks. Do not nest additional triple-backtick code fences inside; when you need to show commands, transcripts, diffs, or code, present them as indented blocks within that single fence. Use indentation for clarity rather than code fences inside an ExecPlan to avoid prematurely closing the ExecPlan's code fence. Use two newlines after every heading, use # and ## and so on, and correct syntax for ordered and unordered lists. - -When writing an ExecPlan to a Markdown (.md) file where the content of the file *is only* the single ExecPlan, you should omit the triple backticks. - -Write in plain prose. Prefer sentences over lists. Avoid checklists, tables, and long enumerations unless brevity would obscure meaning. Checklists are permitted only in the `Progress` section, where they are mandatory. Narrative sections must remain prose-first. - -## Guidelines - -Self-containment and plain language are paramount. If you introduce a phrase that is not ordinary English ("daemon", "middleware", "RPC gateway", "filter graph"), define it immediately and remind the reader how it manifests in this repository (for example, by naming the files or commands where it appears). Do not say "as defined previously" or "according to the architecture doc." Include the needed explanation here, even if you repeat yourself. - -Avoid common failure modes. Do not rely on undefined jargon. Do not describe "the letter of a feature" so narrowly that the resulting code compiles but does nothing meaningful. Do not outsource key decisions to the reader. When ambiguity exists, resolve it in the plan itself and explain why you chose that path. Err on the side of over-explaining user-visible effects and under-specifying incidental implementation details. - -Anchor the plan with observable outcomes. State what the user can do after implementation, the commands to run, and the outputs they should see. Acceptance should be phrased as behavior a human can verify ("after starting the server, navigating to [http://localhost:8080/health](http://localhost:8080/health) returns HTTP 200 with body OK") rather than internal attributes ("added a HealthCheck struct"). If a change is internal, explain how its impact can still be demonstrated (for example, by running tests that fail before and pass after, and by showing a scenario that uses the new behavior). - -Specify repository context explicitly. Name files with full repository-relative paths, name functions and modules precisely, and describe where new files should be created. If touching multiple areas, include a short orientation paragraph that explains how those parts fit together so a novice can navigate confidently. When running commands, show the working directory and exact command line. When outcomes depend on environment, state the assumptions and provide alternatives when reasonable. - -Be idempotent and safe. Write the steps so they can be run multiple times without causing damage or drift. If a step can fail halfway, include how to retry or adapt. If a migration or destructive operation is necessary, spell out backups or safe fallbacks. Prefer additive, testable changes that can be validated as you go. - -Validation is not optional. Include instructions to run tests, to start the system if applicable, and to observe it doing something useful. Describe comprehensive testing for any new features or capabilities. Include expected outputs and error messages so a novice can tell success from failure. Where possible, show how to prove that the change is effective beyond compilation (for example, through a small end-to-end scenario, a CLI invocation, or an HTTP request/response transcript). State the exact test commands appropriate to the project's toolchain and how to interpret their results. - -Capture evidence. When your steps produce terminal output, short diffs, or logs, include them inside the single fenced block as indented examples. Keep them concise and focused on what proves success. If you need to include a patch, prefer file-scoped diffs or small excerpts that a reader can recreate by following your instructions rather than pasting large blobs. - -## Milestones - -Milestones are narrative, not bureaucracy. If you break the work into milestones, introduce each with a brief paragraph that describes the scope, what will exist at the end of the milestone that did not exist before, the commands to run, and the acceptance you expect to observe. Keep it readable as a story: goal, work, result, proof. Progress and milestones are distinct: milestones tell the story, progress tracks granular work. Both must exist. Never abbreviate a milestone merely for the sake of brevity, do not leave out details that could be crucial to a future implementation. - -Each milestone must be independently verifiable and incrementally implement the overall goal of the execution plan. - -## Living plans and design decisions - -* ExecPlans are living documents. As you make key design decisions, update the plan to record both the decision and the thinking behind it. Record all decisions in the `Decision Log` section. -* ExecPlans must contain and maintain a `Progress` section, a `Surprises & Discoveries` section, a `Decision Log`, and an `Outcomes & Retrospective` section. These are not optional. -* When you discover optimizer behavior, performance tradeoffs, unexpected bugs, or inverse/unapply semantics that shaped your approach, capture those observations in the `Surprises & Discoveries` section with short evidence snippets (test output is ideal). -* If you change course mid-implementation, document why in the `Decision Log` and reflect the implications in `Progress`. Plans are guides for the next contributor as much as checklists for you. -* At completion of a major task or the full plan, write an `Outcomes & Retrospective` entry summarizing what was achieved, what remains, and lessons learned. - -# Prototyping milestones and parallel implementations - -It is acceptable—-and often encouraged—-to include explicit prototyping milestones when they de-risk a larger change. Examples: adding a low-level operator to a dependency to validate feasibility, or exploring two composition orders while measuring optimizer effects. Keep prototypes additive and testable. Clearly label the scope as "prototyping"; describe how to run and observe results; and state the criteria for promoting or discarding the prototype. - -Prefer additive code changes followed by subtractions that keep tests passing. Parallel implementations (e.g., keeping an adapter alongside an older path during migration) are fine when they reduce risk or enable tests to continue passing during a large migration. Describe how to validate both paths and how to retire one safely with tests. When working with multiple new libraries or feature areas, consider creating spikes that evaluate the feasibility of these features _independently_ of one another, proving that the external library performs as expected and implements the features we need in isolation. - -## Skeleton of a Good ExecPlan - -```md -# - -This ExecPlan is a living document. The sections `Progress`, `Surprises & Discoveries`, `Decision Log`, and `Outcomes & Retrospective` must be kept up to date as work proceeds. - -If PLANS.md file is checked into the repo, reference the path to that file here from the repository root and note that this document must be maintained in accordance with PLANS.md. - -## Purpose / Big Picture - -Explain in a few sentences what someone gains after this change and how they can see it working. State the user-visible behavior you will enable. - -## Progress - -Use a list with checkboxes to summarize granular steps. Every stopping point must be documented here, even if it requires splitting a partially completed task into two ("done" vs. "remaining"). This section must always reflect the actual current state of the work. - -- [x] (2025-10-01 13:00Z) Example completed step. -- [ ] Example incomplete step. -- [ ] Example partially completed step (completed: X; remaining: Y). - -Use timestamps to measure rates of progress. - -## Surprises & Discoveries - -Document unexpected behaviors, bugs, optimizations, or insights discovered during implementation. Provide concise evidence. - -- Observation: … - Evidence: … - -## Decision Log - -Record every decision made while working on the plan in the format: - -- Decision: … - Rationale: … - Date/Author: … - -## Outcomes & Retrospective - -Summarize outcomes, gaps, and lessons learned at major milestones or at completion. Compare the result against the original purpose. - -## Context and Orientation - -Describe the current state relevant to this task as if the reader knows nothing. Name the key files and modules by full path. Define any non-obvious term you will use. Do not refer to prior plans. - -## Plan of Work - -Describe, in prose, the sequence of edits and additions. For each edit, name the file and location (function, module) and what to insert or change. Keep it concrete and minimal. - -## Concrete Steps - -State the exact commands to run and where to run them (working directory). When a command generates output, show a short expected transcript so the reader can compare. This section must be updated as work proceeds. - -## Validation and Acceptance - -Describe how to start or exercise the system and what to observe. Phrase acceptance as behavior, with specific inputs and outputs. If tests are involved, say "run and expect passed; the new test fails before the change and passes after>". - -## Idempotence and Recovery - -If steps can be repeated safely, say so. If a step is risky, provide a safe retry or rollback path. Keep the environment clean after completion. - -## Artifacts and Notes - -Include the most important transcripts, diffs, or snippets as indented examples. Keep them concise and focused on what proves success. - -## Interfaces and Dependencies - -Be prescriptive. Name the libraries, modules, and services to use and why. Specify the types, traits/interfaces, and function signatures that must exist at the end of the milestone. Prefer stable names and paths such as `crate::module::function` or `package.submodule.Interface`. E.g.: - -In crates/foo/planner.rs, define: - - pub trait Planner { - fn plan(&self, observed: &Observed) -> Vec; - } -``` - -If you follow the guidance above, a single, stateless agent -- or a human novice -- can read your ExecPlan from top to bottom and produce a working, observable result. That is the bar: SELF-CONTAINED, SELF-SUFFICIENT, NOVICE-GUIDING, OUTCOME-FOCUSED. - -When you revise a plan, you must ensure your changes are comprehensively reflected across all sections, including the living document sections, and you must write a note at the bottom of the plan describing the change and the reason why. ExecPlans must describe not just the what but the why for almost everything. diff --git a/CLAUDE.md b/CLAUDE.md index 04fe62e..225a6ae 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -51,7 +51,6 @@ Detailed knowledge is separated into `.claude/skills/`. Loaded automatically or |-------|---------| | `/git-workflow` | Git workflow, branch management, PR creation | | `/agtrace-provider-normalization` | Provider schema investigation and domain abstraction | -| `/execplan` | Execution plan creation for complex features | | `/skill-creator` | Meta-skill for creating new skills | **Usage**: Type `/skill-name` in conversation, or auto-loaded when relevant. @@ -123,7 +122,6 @@ Detailed knowledge is separated into `.claude/skills/`. Loaded automatically or |-------|---------| | `/git-workflow` | Git workflow, branch management, PR creation | | `/agtrace-provider-normalization` | Provider schema investigation and domain abstraction | -| `/execplan` | Execution plan creation for complex features | | `/skill-creator` | Meta-skill for creating new skills | **Usage**: Type `/skill-name` in conversation, or auto-loaded when relevant. From dc88abe96e4dc18e85468222b174c41d314f8f79 Mon Sep 17 00:00:00 2001 From: zawakin Date: Sun, 8 Feb 2026 12:26:44 +0900 Subject: [PATCH 3/4] chore: remove skill-creator skill Co-Authored-By: Claude Opus 4.6 --- .claude/skills/skill-creator/SKILL.md | 299 -------------------------- CLAUDE.md | 2 - 2 files changed, 301 deletions(-) delete mode 100644 .claude/skills/skill-creator/SKILL.md diff --git a/.claude/skills/skill-creator/SKILL.md b/.claude/skills/skill-creator/SKILL.md deleted file mode 100644 index 23cb0b7..0000000 --- a/.claude/skills/skill-creator/SKILL.md +++ /dev/null @@ -1,299 +0,0 @@ ---- -name: skill-creator -description: Skill Creator - Meta-skill for creating new domain-specific skills. Automatically activates when creating skills about specific topics or expertise areas. ---- - -# Skill Creator - Meta-Skill - -You are an expert at creating domain-specific skills for Claude Code. This meta-skill helps you create new skills that capture specialized knowledge about specific parts of the codebase, tools, or workflows. - -## Skill Structure - -Every skill follows this structure: - -``` -.claude/skills// -└── SKILL.md -``` - -## Skill File Format - -A skill MUST have the following frontmatter and structure: - -```markdown ---- -name: -description: ---- - -# - - - -##
- - - -##
- - - -## When to Use This Skill - -This skill should be activated when: -- -- -- - -## - - -``` - -## Frontmatter Requirements - -The frontmatter MUST include: -- **name**: Kebab-case skill name (e.g., `agtrace-cli-expert`, `skill-creator`) -- **description**: One-line description that includes: - - What the skill is about - - When it should be activated - - Often includes "(project)" suffix for project-specific skills - -## Good Skill Characteristics - -### 1. Domain-Specific Knowledge -Skills should capture specialized knowledge about: -- Specific subsystems (e.g., CLI, database layer, parser) -- Tools or workflows (e.g., ExecPlans, testing patterns) -- Architecture patterns (e.g., handler pattern, view abstraction) - -### 2. Self-Contained -Each skill should: -- Be understandable without reading other skills -- Include all necessary context -- Reference specific file paths when relevant -- Define any technical terms used - -### 3. Actionable -Skills should help with: -- Understanding code structure -- Making modifications -- Following established patterns -- Debugging common issues - -### 4. Well-Organized -Use clear sections: -- Overview/Introduction -- Architecture/Structure -- Patterns and conventions -- File organization -- Common tasks or use cases -- When to activate this skill - -## Skill Creation Process - -### Step 1: Research the Domain - -Before creating a skill, thoroughly research: -1. Read relevant source code -2. Understand the architecture -3. Identify key patterns -4. Note important file paths -5. Understand the problem domain - -Use the Task tool with `subagent_type=Explore` for comprehensive codebase exploration. - -### Step 2: Structure the Knowledge - -Organize information into logical sections: -- Start with high-level overview -- Progress to detailed patterns -- Include practical examples -- End with usage guidance - -### Step 3: Create the Skill File - -```bash -# Create directory -mkdir -p .claude/skills/ - -# Write SKILL.md with frontmatter and content -# (Use Write tool) -``` - -### Step 4: Verify - -```bash -# Verify the skill file is readable -cat .claude/skills//SKILL.md -``` - -## Types of Skills to Create - -### 1. Subsystem Expert Skills -Deep knowledge of a specific subsystem: -- Example: `agtrace-cli-expert` (CLI structure and patterns) -- Example: `database-layer-expert` (database schema and queries) -- Example: `parser-expert` (log parsing and schema-on-read) - -### 2. Workflow Skills -Capturing specific workflows: -- Example: `execplan` (creating execution plans) -- Example: `testing-workflow` (testing patterns and practices) -- Example: `release-process` (release and deployment) - -### 3. Tool-Specific Skills -Knowledge about specific tools: -- Example: `rust-best-practices` (Rust patterns in this project) -- Example: `git-workflow` (Git conventions and commit style) -- Example: `ci-cd-expert` (CI/CD pipeline knowledge) - -### 4. Meta Skills -Skills about skills: -- Example: `skill-creator` (this skill!) -- Example: `documentation-generator` (creating docs) - -## Skill Naming Conventions - -Follow these conventions: -- Use kebab-case (lowercase with hyphens) -- Be descriptive but concise -- Include domain or tool name -- Often end with `-expert`, `-workflow`, or similar suffix - -Good examples: -- `agtrace-cli-expert` -- `execplan` -- `skill-creator` -- `database-layer-expert` - -Bad examples: -- `CLI` (too short, not descriptive) -- `the_rust_expert` (use kebab-case) -- `everything-about-parsers-and-schemas` (too long) - -## Example: Creating a New Skill - -Here's a complete example of creating a database expert skill: - -```bash -# 1. Research phase (use Task tool with Explore agent) -# Explore database-related files, schemas, queries - -# 2. Create directory -mkdir -p .claude/skills/database-expert - -# 3. Write SKILL.md (use Write tool) -cat > .claude/skills/database-expert/SKILL.md << 'EOF' ---- -name: database-expert -description: Database Expert - Deep knowledge of agtrace database schema, queries, and indexing strategy. Activates for database-related tasks. ---- - -# Database Expert - -[Content about database structure, schema, common queries, etc.] -EOF - -# 4. Verify -ls -la .claude/skills/database-expert -cat .claude/skills/database-expert/SKILL.md -``` - -## Best Practices - -### DO: -- Research thoroughly before writing -- Include specific file paths and line numbers when relevant -- Provide concrete examples -- Explain architectural patterns -- Define technical terms -- Include "When to Use This Skill" section -- Keep content focused on one domain - -### DON'T: -- Create skills that are too broad -- Duplicate information across skills -- Include outdated information -- Use vague descriptions -- Forget the frontmatter -- Create skills without proper research - -## Updating Existing Skills - -Skills are living documents. Update them when: -- Code structure changes -- New patterns are established -- Better examples are found -- Architecture evolves - -To update: -1. Read the existing skill file -2. Make targeted edits -3. Ensure all sections remain accurate -4. Update any file path references - -## Integration with Claude Code - -Skills are automatically discovered by Claude Code when: -- They are in `.claude/skills/` directory -- They have proper frontmatter -- They follow the SKILL.md naming convention - -Claude will use skills: -- Based on the description in frontmatter -- When user asks related questions -- When working on related code - -## When to Use This Meta-Skill - -Use `skill-creator` when: -- User asks to create a new skill about a topic -- You need to capture specialized knowledge -- You want to document a subsystem or workflow -- Creating documentation for future development -- User explicitly mentions creating a skill or expertise area - -## Common Patterns - -### Pattern 1: Subsystem Deep-Dive - -Research → Structure (Overview, Architecture, Patterns, Files, Tasks) → Write → Verify - -### Pattern 2: Workflow Documentation - -Identify workflow → Document steps → Provide examples → Explain when to use → Write → Verify - -### Pattern 3: Reference Documentation - -Gather facts → Organize by category → Add usage guidance → Write → Verify - -## Troubleshooting - -### Skill Not Appearing - -Check: -1. Frontmatter is properly formatted -2. File exists in `.claude/skills//SKILL.md` -3. File is named `SKILL.md` (case-sensitive) - -### Skill Not Activating - -Check: -1. Description is clear about when to activate -2. Skill content is relevant to the task -3. Frontmatter description matches the content - -## Summary - -This meta-skill enables creation of domain-specific expertise that Claude Code can leverage. By following the structure and best practices outlined here, you can create effective skills that capture specialized knowledge and improve the development experience. - -Key steps: -1. Research thoroughly -2. Structure logically -3. Write with frontmatter to `.claude/skills//SKILL.md` -4. Verify and test - -Remember: -- Skills are living documents. Keep them updated and focused on their specific domain. -- Create files directly in `.claude/skills/`. diff --git a/CLAUDE.md b/CLAUDE.md index 225a6ae..90d7e06 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -51,7 +51,6 @@ Detailed knowledge is separated into `.claude/skills/`. Loaded automatically or |-------|---------| | `/git-workflow` | Git workflow, branch management, PR creation | | `/agtrace-provider-normalization` | Provider schema investigation and domain abstraction | -| `/skill-creator` | Meta-skill for creating new skills | **Usage**: Type `/skill-name` in conversation, or auto-loaded when relevant. @@ -122,7 +121,6 @@ Detailed knowledge is separated into `.claude/skills/`. Loaded automatically or |-------|---------| | `/git-workflow` | Git workflow, branch management, PR creation | | `/agtrace-provider-normalization` | Provider schema investigation and domain abstraction | -| `/skill-creator` | Meta-skill for creating new skills | **Usage**: Type `/skill-name` in conversation, or auto-loaded when relevant. From 62c1f6cb004e3a3f2b1a3c7db7d6c3fc5126999c Mon Sep 17 00:00:00 2001 From: zawakin Date: Sun, 8 Feb 2026 12:28:24 +0900 Subject: [PATCH 4/4] chore: update provider-normalization skill to mise-driven workflow Co-Authored-By: Claude Opus 4.6 --- .../agtrace-provider-normalization/SKILL.md | 136 +++++------------- tasks.toml | 10 ++ 2 files changed, 43 insertions(+), 103 deletions(-) diff --git a/.claude/skills/agtrace-provider-normalization/SKILL.md b/.claude/skills/agtrace-provider-normalization/SKILL.md index cda9d80..ed2d820 100644 --- a/.claude/skills/agtrace-provider-normalization/SKILL.md +++ b/.claude/skills/agtrace-provider-normalization/SKILL.md @@ -7,6 +7,15 @@ description: Investigate AI agent provider tool schemas (Claude Code, Codex, Gem This skill provides deep knowledge of how agtrace normalizes diverse AI agent log formats into unified domain types. Use this when working with provider implementations, tool normalization, or understanding the schema-on-read architecture. +## Quick Reference + +```bash +mise run test:providers # Run provider tests +mise run test:types # Run types tests +mise run lab:grep -- "pattern" --json --limit 5 # Search real event data +mise run verify # Full check (fmt + clippy + test + build) +``` + ## Three-Tier Provider Architecture ### Tier 1: Trait-Based Adapter Pattern @@ -14,9 +23,9 @@ This skill provides deep knowledge of how agtrace normalizes diverse AI agent lo Every provider implements three core traits bundled in a `ProviderAdapter`: ```rust -LogDiscovery → File discovery and session location -SessionParser → Raw log parsing to AgentEvent timeline -ToolMapper → Tool call normalization and classification +LogDiscovery -> File discovery and session location +SessionParser -> Raw log parsing to AgentEvent timeline +ToolMapper -> Tool call normalization and classification ``` **Key Files:** @@ -56,11 +65,9 @@ All providers normalize to common types in `agtrace-types`: ## Schema-on-Read Architecture -The architecture enforces Schema-on-Read where: - 1. **Raw logs are source of truth** - Original files never modified 2. **Lazy parsing** - Files parsed on demand -3. **Type-safe conversion** - Raw JSON → Provider Args → Domain ToolCallPayload +3. **Type-safe conversion** - Raw JSON -> Provider Args -> Domain ToolCallPayload ### Provider-Specific Args Pattern @@ -90,14 +97,14 @@ impl ClaudeReadArgs { ``` Raw JSON Arguments - ↓ + | Provider-specific Args deserialization (strict) - ↓ -Optional: Semantic reclassification (e.g., shell → Read/Write/Search) - ↓ + | +Optional: Semantic reclassification (e.g., shell -> Read/Write/Search) + | Convert to typed ToolCallPayload variant - ↓ -If parse fails → Generic variant (safe fallback) + | +If parse fails -> Generic variant (safe fallback) ``` ### Semantic Reclassification Example @@ -146,7 +153,7 @@ The `EventBuilder` in `builder.rs` provides deterministic event construction: pub struct EventBuilder { session_id: Uuid, stream_tips: HashMap, // Per-stream parent tracking - tool_map: HashMap, // Provider ID → UUID mapping + tool_map: HashMap, // Provider ID -> UUID mapping } ``` @@ -157,76 +164,12 @@ Key features: ## Adding a New Provider -1. **Create provider module**: `crates/agtrace-providers/src//` - -2. **Implement Discovery**: -```rust -pub struct NewProviderDiscovery; - -impl LogDiscovery for NewProviderDiscovery { - fn id(&self) -> &'static str { "new_provider" } - fn probe(&self, path: &Path) -> ProbeResult { ... } - fn scan_sessions(&self, log_root: &Path) -> Result> { ... } -} -``` - -3. **Implement Parser**: -```rust -pub struct NewProviderParser; - -impl SessionParser for NewProviderParser { - fn parse_file(&self, path: &Path) -> Result> { ... } - fn parse_record(&self, content: &str) -> Result> { ... } -} -``` - -4. **Implement ToolMapper**: -```rust -pub struct NewProviderToolMapper; - -impl ToolMapper for NewProviderToolMapper { - fn classify(&self, tool_name: &str) -> (ToolOrigin, ToolKind) { ... } - fn normalize_call(&self, name: &str, args: Value, call_id: Option) - -> ToolCallPayload { ... } - fn summarize(&self, kind: ToolKind, args: &Value) -> String { ... } -} -``` - -5. **Register in registry.rs**: -```rust -pub fn create_adapter(name: &str) -> Result { - match name { - "new_provider" => Ok(ProviderAdapter::new( - Box::new(crate::new_provider::NewProviderDiscovery), - Box::new(crate::new_provider::NewProviderParser), - Box::new(crate::new_provider::NewProviderToolMapper), - )), - // ... - } -} -``` - -## Tool Classification Pattern - -### Provider-Specific Classification - -Each provider defines in `tool_mapping.rs`: -```rust -fn classify_tool(tool_name: &str) -> Option<(ToolOrigin, ToolKind)> -``` - -Returns `Some` if recognized, `None` for fallback. - -### Common Heuristic Fallback - -When provider doesn't recognize a tool (`tool_analyzer.rs`): -```rust -pub fn classify_common(tool_name: &str) -> (ToolOrigin, ToolKind) { - // name.contains("search") → ToolKind::Search - // name.contains("read") → ToolKind::Read - // name.starts_with("mcp__") → ToolOrigin::Mcp -} -``` +1. Create provider module: `crates/agtrace-providers/src//` +2. Implement `LogDiscovery`, `SessionParser`, `ToolMapper` traits +3. Register in `registry.rs` +4. Run `mise run test:providers` to validate +5. Run `mise run lab:grep -- "tool_name" --json --limit 5` to verify against real data +6. Run `mise run verify` before submitting PR ## Key Architectural Decisions @@ -238,7 +181,13 @@ pub fn classify_common(tool_name: &str) -> (ToolOrigin, ToolKind) { | Event IDs | Deterministic v5 UUIDs | Reproducible sessions | | Multi-Stream | Separate parent chains per StreamId | Independent flows | -## Testing Patterns +## Testing + +```bash +mise run test:providers # Run all provider tests +mise run test:types # Run domain type tests +mise run test # Run full test suite +``` Each provider has tests for: - Discovery: probe, scan, session extraction @@ -246,24 +195,6 @@ Each provider has tests for: - Mapper: tool normalization per tool type - Edge cases: malformed data, unknown tools -```rust -#[test] -fn test_normalize_read() { - let payload = normalize_claude_tool_call( - "Read".to_string(), - serde_json::json!({"file_path": "src/main.rs"}), - Some("call_123".to_string()), - ); - - match payload { - ToolCallPayload::FileRead { arguments, .. } => { - assert_eq!(arguments.file_path, Some("src/main.rs".to_string())); - } - _ => panic!("Expected FileRead"), - } -} -``` - ## When to Use This Skill This skill should be activated when: @@ -273,7 +204,6 @@ This skill should be activated when: - Debugging provider-specific parsing issues - Designing new tool classification strategies - Working with MCP tool handling -- Understanding the schema-on-read architecture ## Key Files Reference diff --git a/tasks.toml b/tasks.toml index 3b16efc..a961d76 100644 --- a/tasks.toml +++ b/tasks.toml @@ -35,6 +35,16 @@ run = "cargo fmt --check && cargo clippy --workspace -- -D warnings && cargo tes description = "Accept snapshot changes and show diff" run = "cargo insta accept && git diff" +# --- Provider --- + +["test:providers"] +description = "Run provider tests only" +run = "cargo test -p agtrace-providers" + +["test:types"] +description = "Run types tests only" +run = "cargo test -p agtrace-types" + # --- Lab --- ["lab:grep"]