feat(agents): add task completion rules, skills discovery, and Edit tool

profiles/default/agents/implementation-verifier.md

@@ -1,7 +1,6 @@
 ---
 name: implementation-verifier
 description: Use proactively to verify the end-to-end implementation of a spec
-tools: Write, Read, Bash, WebFetch, Playwright
 color: green
 model: inherit
 ---

profiles/default/agents/implementer.md

@@ -1,7 +1,6 @@
 ---
 name: implementer
 description: Use proactively to implement a feature by following a given tasks.md for a spec.
-tools: Write, Read, Bash, WebFetch, Playwright, Skill
 color: red
 model: inherit
 ---

profiles/default/agents/product-planner.md

@@ -1,7 +1,6 @@
 ---
 name: product-planner
 description: Use proactively to create product documentation including mission, and roadmap
-tools: Write, Read, Bash, WebFetch
 color: cyan
 model: inherit
 ---

profiles/default/agents/spec-initializer.md

@@ -1,7 +1,6 @@
 ---
 name: spec-initializer
 description: Use proactively to initialize spec folder and save raw idea
-tools: Write, Bash
 color: green
 model: sonnet
 ---

profiles/default/agents/spec-shaper.md

@@ -1,7 +1,6 @@
 ---
 name: spec-shaper
 description: Use proactively to gather detailed requirements through targeted questions and visual analysis
-tools: Write, Read, Bash, WebFetch, Skill
 color: blue
 model: inherit
 ---

profiles/default/agents/spec-verifier.md

@@ -1,7 +1,6 @@
 ---
 name: spec-verifier
 description: Use proactively to verify the spec and tasks list
-tools: Write, Read, Bash, WebFetch, Skill
 color: pink
 model: sonnet
 ---

profiles/default/agents/spec-writer.md

@@ -1,7 +1,6 @@
 ---
 name: spec-writer
 description: Use proactively to create a detailed specification document for development
-tools: Write, Read, Bash, WebFetch, Skill
 color: purple
 model: inherit
 ---

profiles/default/agents/tasks-list-creator.md

@@ -1,7 +1,6 @@
 ---
 name: task-list-creator
 description: Use proactively to create a detailed and strategic tasks list for development of a spec
-tools: Write, Read, Bash, WebFetch, Skill
 color: orange
 model: inherit
 ---

profiles/default/commands/implement-tasks/multi-agent/implement-tasks.md

@@ -3,7 +3,7 @@
 Now that we have a spec and tasks list ready for implementation, we will proceed with implementation of this spec by following this multi-phase process:
 
 PHASE 1: Determine which task group(s) from tasks.md should be implemented
-PHASE 2: Delegate implementation to the implementer subagent
+PHASE 2: Delegate implementation to implementer subagents (one per task group)
 PHASE 3: After ALL task groups have been implemented, delegate to implementation-verifier to produce the final verification report.
 
 Follow each of these phases and their individual workflows IN SEQUENCE:
@@ -14,7 +14,7 @@ Follow each of these phases and their individual workflows IN SEQUENCE:
 
 First, check if the user has already provided instructions about which task group(s) to implement.
 
-**If the user HAS provided instructions:** Proceed to PHASE 2 to delegate implementation of those specified task group(s) to the **implementer** subagent.
+**If the user HAS provided instructions:** Proceed to PHASE 2 to delegate implementation of those specified task group(s) to **implementer** subagents (one per task group).
 
 **If the user has NOT provided instructions:**
 
@@ -26,22 +26,39 @@ Should we proceed with implementation of all task groups in tasks.md?
 If not, then please specify which task(s) to implement.
 ```
 
-### PHASE 2: Delegate implementation to the implementer subagent
+### PHASE 2: Delegate implementation to implementer subagents
 
-Delegate to the **implementer** subagent to implement the specified task group(s):
+**CRITICAL: Spawn a SEPARATE implementer subagent for EACH task group.** Each subagent gets its own context window, enabling focused and effective implementation.
 
-Provide to the subagent:
-- The specific task group(s) from `agent-os/specs/[this-spec]/tasks.md` including the parent task, all sub-tasks, and any sub-bullet points
+**Execution strategy based on task group dependencies:**
+
+1. **Analyze dependencies** - Check for "Dependencies:" annotations in tasks.md for each task group
+2. **Independent task groups** (no dependencies, or all dependencies already completed): Launch their implementer subagents **IN PARALLEL** by issuing multiple Task tool calls in a single message
+3. **Dependent task groups**: Wait for the required dependency to complete before launching
+
+**For EACH task group, spawn a dedicated implementer subagent providing:**
+
+- **ONE specific task group** from `agent-os/specs/[this-spec]/tasks.md` (including the parent task, all sub-tasks, and any sub-bullet points)
 - The path to this spec's documentation: `agent-os/specs/[this-spec]/spec.md`
 - The path to this spec's requirements: `agent-os/specs/[this-spec]/planning/requirements.md`
 - The path to this spec's visuals (if any): `agent-os/specs/[this-spec]/planning/visuals`
 
-Instruct the subagent to:
+Instruct each subagent to:
 1. Analyze the provided spec.md, requirements.md, and visuals (if any)
 2. Analyze patterns in the codebase according to its built-in workflow
 3. Implement the assigned task group according to requirements and standards
 4. Update `agent-os/specs/[this-spec]/tasks.md` to mark completed tasks with `- [x]`
 
+**Example: Parallel execution**
+If Task Group 1 and Task Group 2 have no dependencies on each other, launch both implementer subagents in a single message:
+- Task tool call #1: implementer for Task Group 1
+- Task tool call #2: implementer for Task Group 2
+
+**Example: Sequential execution**
+If Task Group 3 depends on Task Group 1:
+1. Wait for Task Group 1 implementer to complete
+2. Then launch Task Group 3 implementer
+
 ### PHASE 3: Produce the final verification report
 
 IF ALL task groups in tasks.md are marked complete with `- [x]`, then proceed with this step.  Otherwise, return to PHASE 1.

profiles/default/commands/improve-skills/improve-skills.md

@@ -1,7 +1,5 @@
 I want you to help me improve the files that make up my Claude Code Skills by rewriting their descriptions so that they can be more readily discovered and used by Claude Code when it works on coding tasks.
 
-You can refer to the Claude Code documentation on the Skills feature here: https://docs.claude.com/en/docs/claude-code/skills
-
 All of the Skills in our project are located in `.claude/skills/`. Each Skill has its own folder and inside each Skill folder is a file called `SKILL.md`.
 
 LOOP through each `SKILL.md` file and FOR EACH use the following process to revise its content and improve it:
@@ -18,35 +16,207 @@ Before I proceed with improving your Claude Code Skills, can you confirm that yo
 If not, then please specify which Skills I should include or exclude.
 ```
 
+---
+
+## Skills Writing Reference
+
+Before improving skills, understand these key concepts:
+
+### Critical: Three-Phase Loading Model
+
+```
+Phase 1: YAML frontmatter cached for ALL skills
+    ↓
+Phase 2: SKILL.md loaded when model decides to use skill
+    ↓
+Phase 3: Related files loaded based on links + context
+```
+
+**Implications:**
+- `description` must contain trigger patterns (Phase 1 decision)
+- SKILL.md must be SHORT - loaded before full context known
+- Related files can be LONGER - loaded only when needed
+- Links must have context descriptions (when to load each file)
+
+### Supported YAML Frontmatter Fields
+
+| Field | Required | Purpose |
+|-------|----------|---------|
+| `name` | **yes** | Identifier (lowercase, hyphens, max 64 chars). Must match directory name. |
+| `description` | **yes** | **Critical for triggering.** Max 1024 chars |
+| `when_to_use` | no | Additional trigger guidance |
+| `allowed-tools` | no | Restrict available tools |
+
+### Unsupported Fields - REMOVE If Present
+
+These fields are **ignored** by Claude Code:
+- `tags` - not supported
+- `version` - not supported
+- `dependencies` - not supported
+
+### Description Patterns
+
+```yaml
+# Standard triggers - list scenarios:
+description: "Use when writing database queries, creating migrations, working with Prisma models"
+
+# Mandatory loading (always load):
+description: "MANDATORY: Project coding standards. Use for all code in this project"
+
+# Combined with when_to_use:
+description: "Database patterns and best practices"
+when_to_use: "When working with PostgreSQL, Prisma, or SQL queries"
+
+# File type triggers:
+description: "Tailwind CSS patterns. Use when writing .tsx, .vue, .css files with utility classes"
+
+# Comprehensive (recommended for max discoverability):
+description: "Write accessible React components. Use when creating .tsx files, implementing ARIA attributes, keyboard navigation, or fixing accessibility issues"
+```
+
+### Compactness Principle
+
+**Skills consume context window. Every character matters.**
+
+- Short, clear descriptions with triggers
+- Minimal SKILL.md content - only essentials
+- **Illustrative examples**: 3-5 lines max (showing concept)
+- **Reference patterns**: Can be longer if they provide copy-paste value
+- Link to supporting files for details
+
+### File Structure Options
+
+**Minimal:**
+```
+skill-name/
+└── SKILL.md
+```
+
+**With Supporting Files:**
+```
+skill-name/
+├── SKILL.md          # Overview + links (SHORT)
+├── REFERENCE.md      # Detailed info
+└── EXAMPLES.md       # Code examples
+```
+
+**Multi-topic (preferred for context efficiency):**
+```
+skill-name/
+├── SKILL.md              # Core rules + short illustrative examples
+├── EXAMPLES-QUERIES.md   # Examples for database queries
+├── EXAMPLES-MIGRATIONS.md # Examples for migrations
+└── EXAMPLES-MODELS.md    # Examples for models
+```
+
+### Quick Template
+
+```markdown
+---
+name: my-skill
+description: "Use when [specific trigger situations]"
+---
+
+# My Skill
+
+## When to use this skill
+
+- When writing or editing [file types]
+- When implementing [features]
+- When debugging [issues]
+
+## Purpose
+[One sentence]
+
+## Instructions
+1. Step one
+2. Step two
+
+## Example
+\`\`\`code
+// 3-5 lines max
+\`\`\`
+```
+
+---
+
 ### Step 2: Analyze what this Skill does
 
 Analyze and read the skill file to understand what it is, what it should be used for, and when it should be used. The specific best practices are described and linked within it. Look to these places to read and understand each skill:
 
 - The Skill's name and file name.
 - The Skill.md contains a link that points to `agent_os/standards/...` — Follow that link and read its contents.
 
-### Step 3: Rewrite the Skill description
+### Step 3: Normalize the Skill name and rewrite the description
+
+#### 3.1: Convert the skill name to kebab-case
+
+Transform the `name` field in the frontmatter to kebab-case format:
+- Convert all letters to lowercase
+- Replace all whitespace characters (spaces, tabs) with a single hyphen
+- Collapse multiple consecutive spaces/hyphens into a single hyphen
+- Trim leading/trailing hyphens if present
+
+Example transformations:
+- `"API Standards"` → `"api-standards"`
+- `"Vue  Component   Guidelines"` → `"vue-component-guidelines"`
+- `"TypeScript Best Practices"` → `"typescript-best-practices"`
+
+#### 3.2: Rewrite the description
 
 The most important element of a skill.md file that impacts its discoverability and trigger-ability by Claude Code is the content we write in the `description` in the skill.md frontmatter.
 
-Rewrite this description using the following guidelines:
+**Algorithm for maximum discoverability:**
 
-- The first sentence should clearly describe what this skill is. For example: "Write Tailwind CSS code and structure front-end UIs using Tailwind CSS utility classes."
-- The second sentence and subsequent sentences should clearly and directly describe multiple examples where and when this skill should be used.
-- The use case examples can include "When writing or editing [file types]" where [file types] can be a list of file extensions or types of files or components commonly found in software projects.
-- The use case examples can also include situations or areas or tools where using this skill should come into play.
-- The description text can be long. There is no maximum character or word limit.
-- Focus on adding examples where the skill SHOULD be used. Do not include instructions on when NOT to use a skill (our goal is for the Skill to be readily found and used frequently).
+1. **First sentence:** Clearly state what the skill does
+   ```
+   "Write Tailwind CSS code and structure front-end UIs using utility classes."
+   ```
+
+2. **Following sentences:** List specific trigger scenarios using these patterns:
+   - **File types:** "When writing or editing .tsx, .vue, .css files"
+   - **Situations:** "When creating forms, layouts, or responsive designs"
+   - **Tools/technologies:** "When using PostCSS, CSS-in-JS, or styled-components"
+   - **Actions:** "When debugging, optimizing, or refactoring [specific area]"
+
+**Key principle:** Focus ONLY on when to USE the skill.
+Never include when NOT to use - this reduces discoverability.
+
+**Longer descriptions are better:** More trigger scenarios = higher discoverability.
+Use the full 1024 chars if needed.
+
+**Good vs Bad Examples:**
+```yaml
+# Bad - too vague, won't trigger:
+description: "Helps with database"
+
+# Good - specific triggers:
+description: "Use when connecting to PostgreSQL/MySQL, writing queries, or debugging database issues"
+
+# Better - multiple trigger scenarios:
+description: "API documentation generator. Use when documenting REST endpoints, creating OpenAPI specs, writing JSDoc comments, or generating SDK documentation"
+```
+
+#### 3.3: Remove unsupported fields
+
+Check YAML frontmatter and REMOVE these fields if present:
+- `tags`
+- `version`
+- `dependencies`
+
+These fields are ignored by Claude Code and should be removed.
 
 ### Step 4: Insert a section for 'When to use this skill'
 
 At the top of the content of skill.md, below the frontmatter, insert an H2 heading, "When to use this skill" followed by a list of use case examples.
 
 The use case examples can repeat the same one(s) listed in the description and/or expand on them.
 
+**Tip:** This section has no character limit (unlike description's 1024 chars), so you can expand on triggers mentioned in the description and add more specific scenarios.
+
 Example:
 ```markdown
-## When to use this skill:
+## When to use this skill
 
 - [Descriptive example A]
 - [Descriptive example B]
@@ -56,19 +226,30 @@ Example:
 
 ### Step 5: Advise the user on improving their skills further
 
-After revising ALL Skill.md files located in the project's `.claude/skills/` folder, display the following message to the user to advise them on how to improve their Claude Code Skills further:
+After revising ALL Skill.md files located in the project's `.claude/skills/` folder, display the following message to the user:
 
 ```
 All Claude Code Skills have been analyzed and revised!
 
-RECOMMENDATION 👉 Review and revise them further using these tips:
+## Quality Checklist
 
-- Make Skills as descriptive as possible
-- Use their 'description' frontmatter to tell Claude Code when it should proactively use this skill.
-- Include all relevant instructions, details and directives within the content of the Skill.
-- You can link to other files (like your Agent OS standards files) using markdown links.
-- You can consolidate multiple similar skills into single skills where it makes sense for Claude to find and use them together.
+Verify each skill meets these criteria:
 
-For more best practices, refer to the official Claude Code documentation on Skills:
-https://docs.claude.com/en/docs/claude-code/skills
+- [ ] `description` contains specific trigger patterns
+- [ ] Has "When to use this skill" section at top of content
+- [ ] No `tags`/`version`/`dependencies` fields (unsupported)
+- [ ] SKILL.md is SHORT (loaded early, before full context)
+- [ ] Illustrative examples are short (3-5 lines)
+- [ ] Links have context descriptions (when to load each file)
+- [ ] One skill = one capability (focused scope)
+
+## Additional Recommendations
+
+- **Compactness:** Skills consume context window. Every character matters.
+- **Triggering:** Description determines when skill loads - make it as specific as possible.
+- **Progressive disclosure:** SKILL.md loads first, supporting files only when needed.
+- **Multi-topic skills:** Split examples into separate files by topic for context efficiency.
+- **Content completeness:** Include all relevant instructions, details and directives within the content of the Skill.
+- You can link to other files (like your Agent OS standards files) using markdown links.
+- Consolidate similar skills where it makes sense for Claude to find and use them together.
 ```