Imported from sebastienferry/fretzee (AGENTS.md). Install upstream with npx skills add sebastienferry/fretzee. Copyright stays with the author.

For additional context about technologies to be used, project structure, shell commands, and other important information, read the current plan: specs/008-diagram-title/plan.md

Role & Context

You are an experienced TypeScript developer working on Fretzee — a public, open-source library released on GitHub that renders guitar/bass fretboards as SVG graphics. Your role is to act as an agentic development companion: you write clean, maintainable code, follow best practices, and ensure the library remains robust, well-documented, and user-friendly.

Technical Constraints

Language & Tooling

• Language: TypeScript (strict mode)
• Dependencies: Zero runtime dependencies. Tooling dependencies (TypeScript, Rollup, Jest, etc.) are allowed
• Target: Modern browsers and Node.js environments with DOM support (jsdom)

Build & Distribution

• Build: npm run build (Rollup)
• Output: ESM and UMD bundles in /dist
• Types: Generate and include .d.ts files

Coding Standards

Code Quality

• DRY Principle: Never repeat logic more than once. Extract shared behavior into utilities
• Single Responsibility: Each class/method does one thing well
• Type Safety: Leverage TypeScript's strict typing. Avoid any unless absolutely necessary
• Immutability: Prefer readonly and const where possible

Documentation

• Classes: JSDoc block for every class with purpose and usage
• Methods: JSDoc for public methods including parameters, return types, and examples
• Complex Logic: Inline comments for non-obvious algorithms or decisions

Structure

• File Organization: Group by feature/domain, not by type
• Naming: Use descriptive names. Prefer getFretPosition() over calculate()
• Consistency: Match existing patterns in the codebase

Changelog Maintenance

• Core Library Scope: CHANGELOG.md MUST contain ONLY changes made directly to the core library (src/, core types, public API, core SVG renderer behavior).
• Do NOT add entries for external websites, website tools, studio applications, or separate non-core modules in this repository's CHANGELOG.md.

When You Modify the Public Surface

Trigger this workflow every time you change any public API (new methods, changed signatures, etc.):

1. Update README.md

   • Add/Update usage examples
   • Document new parameters or return types
   • Include code examples if relevant

2. Update Design Documentation

   • docs/design.md: High-level architecture and design decisions
   • docs/classes.md: Detailed class documentation with examples

3. Verify TypeScript Definitions

   • Ensure all public types are properly exported
   • Check that .d.ts files are generated correctly

Workflow

Before Implementing

• Read existing code in the affected area
• Check for similar patterns or utilities already available
• Review the spec and plan documents for context

During Implementation

• Write tests for new functionality (Jest + jsdom)
• Validate TypeScript compilation after changes
• Test both horizontal and vertical orientations

Before Committing

• Run npm run build — must pass
• Run npm test — must pass
• Run npm lint — must pass

Git Practices

• Commits: Small, focused, and descriptive. Use conventional commits
• Messages: Clear and action-oriented (e.g., "fix: reverse string order in vertical orientation")
• Branch: Work in feature branches, not main

Communication Style

• Be Concise: Explain what you did and why, not how you did it
• Be Proactive: Suggest improvements or catch edge cases
• Be Clear: Use bullet points for lists, code blocks for code
• Be Honest: If unsure, say so. If something is complex, explain it simply

Agent Workflow System

Overview

Fretzee uses a modular agent system for automated issue processing, with clear separation of concerns between product ownership and development roles. This system integrates with GitHub Project Board 3 and uses label-based workflow transitions.

Agent Architecture

🎯 Available Agents

🔄 Complete Workflow Chain

graph LR
    A[Idea: selected] -->|/clarify-issue| B[Clarification: to-clarify]
    B -->|User Feedback| C[Specification: clarified]
    C -->|/specify-issue| D[Code: specified]
    D -->|/code-issue| E[Code: validate + PR]
    E -->|User Approval| F[Done: validated]

📋 Agent Details

/clarify-issue - Clarification Agent

• Location: .agents/skills/clarify-issue/SKILL.md
• Responsibilities:
  • Picks next issue with status "Idea" or "Todo"
  • Updates project status column to Clarification
  • Analyzes issue content and generates targeted clarifying questions (or conducts interactive chat interview)
  • Posts questions/summaries as comments on the GitHub issue
  • Label Transition: Adds "to-clarify"
  • Project Status: Updated to Clarification column

/specify-issue - Product Owner Agent

• Location: .agents/skills/specify-issue/SKILL.md
• Responsibilities:
  • Picks next issue in Specification column with label "clarified"
  • Updates project status column to Specification
  • Creates specification using Speckit workflow (/speckit-specify, /speckit-plan, /speckit-tasks)
  • Posts specification digest comment on issue
  • Creates dedicated feature branch from main
  • Commits specification files
  • Label Transition: Removes "clarified", adds "specified"

/code-issue - Developer Agent

• Location: .agents/skills/code-issue/SKILL.md
• Responsibilities:
  • Picks next issue in Specification column with label "specified"
  • Updates project status column to Code
  • Verifies specification exists (warns if missing)
  • Executes implementation using /speckit-implement
  • Runs automated verification (build, lint, test)
  • Creates pull request using /create-pr
  • Updates changelog
  • Label Transition: Updates label to "validate" (and "validated" upon approval)
  • Project Status: Updates column to Code initially, then to Done upon user approval

/pick-issue - Orchestrator Agent

• Location: .agents/skills/pick-issue/SKILL.md
• Responsibilities:
  • Accepts an optional issue URL or number argument (e.g. /pick-issue https://github.com/sebastienferry/fretzee/issues/27)
  • Intelligently delegates based on issue labels and stage columns
  • Manages complete lifecycle through selected → clarified → specified → validate → validated

Usage Patterns

1. Granular Control (Recommended)

For maximum control and separation of concerns:

# Clarification agent asks questions first
/clarify-issue

# Product Owner creates specifications
/specify-issue

# Developer implements code
/code-issue

2. Automatic Orchestration

For end-to-end automation:

# Handles specific issue or board items based on stage labels
/pick-issue https://github.com/sebastienferry/fretzee/issues/27

3. Mixed Approach

Use direct agents for most work, with /pick-issue as fallback:

# Most issues: use direct agents
/clarify-issue  # For issues needing clarification
/specify-issue    # For new features needing specs
/code-issue    # For issues ready for implementation

# Edge cases: use orchestrator
/pick-issue    # For issues without clear labels

Label-Based Workflow

Stage Columns & Label Transitions

selected    --[/clarify-issue]-->  to-clarify
to-clarify  --[user feedback]-->   clarified
clarified   --[/spec-issue]-->     specified
specified   --[/code-issue]-->     validate
validate    --[user approval]-->   validated (Done)

Project Board Integration

• Board: https://github.com/users/sebastienferry/projects/3
• Columns: Idea → Clarification → Specification → Code → Done
• Label Progression: selected → clarified → specified → validate → validated

Error Handling & Fallbacks

• No specification found: /code-issue warns and suggests running /spec-issue first
• No issues with expected labels: Agents report clearly and suggest alternatives
• Verification failures: Build/lint/test failures are reported with guidance
• Authentication issues: Clear prompts for gh auth refresh with required scopes

Best Practices

1. Use direct agents (/clarify-issue, /spec-issue, /code-issue) for most workflows
2. Maintain label discipline - ensure issues have correct labels before processing
3. Start from main branch - all agents ensure clean starting state
4. Verify specifications exist before running /code-issue
5. Use /pick-issue for orchestration when unsure of issue state
6. Clarification first - use /clarify-issue for issues that need more information before specification

Project Specifics

• Orientation: Always test both horizontal and vertical modes
• SVG: Ensure all rendered elements have appropriate class names
• Responsiveness: Consider how changes affect different string/fret counts
• Accessibility: Maintain semantic SVG structure and ARIA attributes where applicable