@datatamer.ai/agentdev 1.0.1

package/skills/auto-ticket-workflow.md

@@ -0,0 +1,542 @@
+---
+name: "auto-ticket-workflow"
+description: "Process GitHub tickets with @claude tag through full development lifecycle: create OpenSpec, implement, test locally, deploy to production, test production, and move to Done"
+dependencies:
+  - gh (GitHub CLI)
+  - kubectl
+  - openspec
+---
+
+# Auto-Ticket Workflow Skill
+
+Automates the entire ticket lifecycle from GitHub project board through development, testing, and deployment.
+
+## IMPORTANT: Execution Rules
+
+**This skill runs FULLY AUTOMATICALLY. DO NOT ask user for permission at any step.**
+
+- Execute all commands immediately without confirmation
+- Run ALL phases (0-7) sequentially WITHOUT pausing between phases
+- After completing each phase, IMMEDIATELY start the next phase
+- Only stop if there's an actual error or failure
+- The user has already authorized the workflow by invoking this skill
+
+## CRITICAL: Screenshot & Image Size Limit
+
+**Claude's vision API has a 2000px per-dimension limit for multi-image requests.** To avoid failures:
+
+- **Playwright viewport**: Always use `1920x1080` (NOT 2560x1440)
+- **Never read screenshots larger than 1920px** with the Read tool — resize first
+- When taking screenshots with Playwright, use: `viewport: { width: 1920, height: 1080 }`
+- If you need to resize an existing image: `npx sharp-cli resize 1920 -i input.png -o output.png` or use ImageMagick: `convert input.png -resize 1920x1080 output.png`
+
+## CRITICAL: NO Nested Skills
+
+**DO NOT use the Skill tool to invoke other skills.** This causes the workflow to stop prematurely.
+
+Instead, all OpenSpec operations are INLINED in this skill:
+- Phase 2 contains the full opsx:ff logic
+- Phase 3 contains the full opsx:apply logic
+
+## CRITICAL: Output Progress
+
+**Always output status messages to show progress:**
+- Print "=== PHASE X: <name> ===" when starting each phase
+- Print command output or summaries after running commands
+- Print "✓ <action> complete" after completing steps
+- Print errors immediately if they occur
+- NEVER run silently - the user needs to see what's happening
+
+## Check for New Comments Between Phases
+
+**Between every phase transition**, check if new comments have been posted on the ticket:
+
+```bash
+if [ -f "$COMMENT_SIGNAL_FILE" ]; then
+  echo "📬 New comments detected!"
+  cat "$COMMENT_SIGNAL_FILE"
+  rm "$COMMENT_SIGNAL_FILE"
+fi
+```
+
+**Rules:**
+- If the signal file exists, read it, then delete it
+- New comments may contain updated requirements — adjust your work accordingly
+- Comments from bot accounts (starting with "🤖") are status updates — ignore them
+- The most recent human comment takes priority over earlier instructions
+- If a comment says to stop or cancel, halt the workflow and comment on the issue
+
+## GitHub Project Configuration
+
+```
+Project: data-tamer (Project #1)
+Project ID: PVT_kwDOCJIWbs4AnuSZ
+Status Field ID: PVTSSF_lADOCJIWbs4AnuSZzgfaWGs
+
+Status Options:
+- Todo: f75ad846
+- In Progress: 47fc9ee4
+- test: c48bc058
+- Done: 98236657
+```
+
+## RELIABLE Status Transitions
+
+**CRITICAL: Always verify status changes succeeded.**
+
+For EVERY status change:
+1. Run the `gh project item-edit` command
+2. Verify by querying the item status
+3. If failed, retry once
+4. Print confirmation: "✓ Ticket #X moved to <status>"
+
+**Status Change Template:**
+```bash
+# Change status
+gh project item-edit --id <item-id> --project-id PVT_kwDOCJIWbs4AnuSZ \
+  --field-id PVTSSF_lADOCJIWbs4AnuSZzgfaWGs \
+  --single-select-option-id <option-id>
+
+# Verify (query the specific item)
+gh api graphql -f query='query { node(id: "<item-id>") { ... on ProjectV2Item { fieldValueByName(name: "Status") { ... on ProjectV2ItemFieldSingleSelectValue { name } } } } }' | jq -r '.data.node.fieldValueByName.name'
+```
+
+**Status Option IDs:**
+- Todo: `f75ad846`
+- In Progress: `47fc9ee4`
+- test: `c48bc058`
+- Done: `98236657`
+
+## Workflow Phases
+
+### Phase 0: Preflight — Read Ticket Status & Comments
+
+**This phase determines the ticket's current state and reads ALL context before doing anything.**
+
+**CRITICAL JQ NOTE:** Do NOT use `!= null` in jq commands - it causes shell escaping errors.
+
+**Step 1: ALWAYS read the ticket body and ALL comments first:**
+```bash
+# Read issue body
+agentdev gh issue view <issue-number> -R data-tamer/<repo> --json title,body,labels,assignees
+
+# Read ALL comments (CRITICAL — follow-up comments override the original body)
+agentdev gh api rest 'repos/data-tamer/<repo>/issues/<issue-number>/comments' | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{JSON.parse(d).forEach(c=>console.log('---',c.user.login,c.created_at,'---\n'+c.body+'\n'))})"
+```
+
+**Comment Priority Rules:**
+- Follow-up comments contain updated requirements that **OVERRIDE** the original ticket body
+- Bot comments (starting with "🤖") are status updates — skip them when reading requirements
+- Always prioritize the **most recent non-bot @claude comment** as the primary requirement
+- If comments say "take screenshots from X" or "use real data from Y", do exactly that
+
+**Step 2: Check the ticket's current project board status:**
+```bash
+# Get all project items
+gh api graphql -f query='query { organization(login: "data-tamer") { projectV2(number: 1) { items(first: 100, orderBy: {field: POSITION, direction: DESC}) { nodes { id fieldValueByName(name: "Status") { ... on ProjectV2ItemFieldSingleSelectValue { name } } content { ... on Issue { number title body repository { name } } } } } } } }' > /tmp/gh-items.json
+
+# Find THIS ticket's status and item ID
+cat /tmp/gh-items.json | jq -r '.data.organization.projectV2.items.nodes[] | select(.content.number == <issue-number>) | select(.content.repository.name == "<repo>") | "\(.id)|\(.fieldValueByName.name)"' 2>/dev/null | head -1
+```
+
+**Step 3: Resume from the right phase based on current status:**
+
+| Current Status | Action |
+|---|---|
+| **Done** | Ticket already complete. If comments contain new @claude requests, move back to "In Progress" and go to Phase 3 |
+| **test** | Skip to Phase 6 (Production Testing) |
+| **In Progress** | Check if OpenSpec exists. If yes → Phase 3 (Implementation). If no → Phase 2 (OpenSpec) |
+| **Todo** | Proceed to Phase 1 (Discovery & Claim) |
+| **Not on board** | Proceed to Phase 1 (Discovery & Claim) |
+
+**Before continuing, check for new comments** (see "Check for New Comments Between Phases" above).
+
+### Phase 1: Ticket Discovery & Claim
+
+**If the ticket is already known** (passed via executor prompt), skip discovery and use that ticket directly.
+
+**If no specific ticket was given**, find tickets in "Todo" status with `@claude` in the body or comments:
+
+```bash
+# Reuse /tmp/gh-items.json from Phase 0 if available, otherwise fetch:
+gh api graphql -f query='query { organization(login: "data-tamer") { projectV2(number: 1) { items(first: 100, orderBy: {field: POSITION, direction: DESC}) { nodes { id fieldValueByName(name: "Status") { ... on ProjectV2ItemFieldSingleSelectValue { name } } content { ... on Issue { number title body repository { name } } } } } } } }' > /tmp/gh-items.json
+
+# Filter for Todo items with @claude
+cat /tmp/gh-items.json | jq -r '.data.organization.projectV2.items.nodes[] | select(.fieldValueByName.name == "Todo") | select(.content.body | contains("@claude")) | "\(.id)|\(.content.number)|\(.content.title)|\(.content.repository.name)"' 2>/dev/null | head -1
+```
+
+**Expected output format:** `ITEM_ID|ISSUE_NUMBER|TITLE|REPO_NAME`
+
+If no tickets found: Report "No @claude tickets found in Todo status." and stop.
+
+If ticket found, extract and store:
+- `item_id`: First field (for project status updates)
+- `issue_number`: Second field
+- `title`: Third field
+- `repo`: Fourth field (e.g., data-tamer-dashboard)
+
+**Before continuing, check for new comments** (see "Check for New Comments Between Phases" above).
+
+### Phase 2: OpenSpec Creation (INLINED - NO Skill tool)
+
+**This phase creates OpenSpec artifacts WITHOUT calling the Skill tool.**
+
+1. **Read the full ticket details AND all comments:**
+```bash
+# Read the issue body
+gh issue view <issue-number> -R data-tamer/<repo> --json title,body,labels,assignees
+
+# CRITICAL: Read ALL issue comments (follow-up instructions override the original body)
+agentdev gh api rest 'repos/data-tamer/<repo>/issues/<issue-number>/comments' | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{JSON.parse(d).forEach(c=>console.log('---',c.user.login,c.created_at,'---\n'+c.body+'\n'))})"
+```
+
+**IMPORTANT: Comment Priority Rules:**
+- Follow-up comments contain updated requirements that **OVERRIDE** the original ticket body
+- When a ticket is re-queued after completion, the **latest @claude comments** explain what needs to change
+- Always prioritize the **most recent non-bot comment** over the original issue body
+- Bot comments (starting with "🤖") are status updates — skip them when reading requirements
+- If comments say "take screenshots from X" or "use real data from Y", do exactly that — do NOT create synthetic/mock UI
+
+2. **Derive a kebab-case change name** from the ticket title (e.g., "Fix slide loading" → `fix-slide-loading`)
+
+3. **Create the OpenSpec change:**
+```bash
+openspec new change "<change-name>"
+```
+
+4. **Get artifact build order:**
+```bash
+openspec status --change "<change-name>" --json
+```
+Parse the JSON to get `applyRequires` (artifacts needed before implementation).
+
+5. **Create artifacts in sequence:**
+
+For each artifact in dependency order:
+```bash
+# Get instructions for the artifact
+openspec instructions <artifact-id> --change "<change-name>" --json
+```
+- Read the `template` from instructions
+- Read any dependency files for context
+- Create the artifact file following the template structure
+- Print "✓ Created <artifact-id>"
+
+Continue until all `applyRequires` artifacts are complete.
+
+6. **Comment on GitHub issue:**
+```bash
+gh issue comment <issue-number> -R data-tamer/<repo> --body "## OpenSpec Change Created
+
+Change: \`<change-name>\`
+Starting automated implementation.
+
+---
+*Automated by Claude Code Auto-Ticket Workflow*"
+```
+
+**After Phase 2: Print "✓ OpenSpec artifacts created. CONTINUING TO PHASE 3..." and IMMEDIATELY proceed.**
+
+**Before continuing, check for new comments** (see "Check for New Comments Between Phases" above).
+
+### Phase 3: Implementation (INLINED - NO Skill tool)
+
+**This phase implements tasks WITHOUT calling the Skill tool.**
+
+1. **Move ticket to "In Progress" and VERIFY:**
+```bash
+# Move to In Progress
+gh project item-edit --id <item-id> --project-id PVT_kwDOCJIWbs4AnuSZ \
+  --field-id PVTSSF_lADOCJIWbs4AnuSZzgfaWGs \
+  --single-select-option-id 47fc9ee4
+
+# Verify the change
+gh api graphql -f query='query { node(id: "<item-id>") { ... on ProjectV2Item { fieldValueByName(name: "Status") { ... on ProjectV2ItemFieldSingleSelectValue { name } } } } }' | jq -r '.data.node.fieldValueByName.name'
+```
+Print "✓ Ticket #<number> moved to In Progress (verified)"
+
+2. **Find the OpenSpec change:**
+```bash
+ls openspec/changes/ | grep -v archive
+```
+Use the change name from Phase 2 or find a matching change.
+
+3. **Get apply instructions:**
+```bash
+openspec instructions apply --change "<change-name>" --json
+```
+This returns context files and task list.
+
+4. **Read context files** listed in `contextFiles` (proposal, specs, design, tasks).
+
+5. **Implement tasks one by one:**
+
+For each pending task in tasks.md:
+- Print "Working on task: <task description>"
+- Make the code changes required
+- Keep changes minimal and focused
+- Mark task complete: `- [ ]` → `- [x]`
+- Print "✓ Task complete"
+
+6. **Commit changes:**
+```bash
+git add <changed-files>
+git commit -m "fix/feat: <description>
+
+Fixes #<issue-number>
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
+```
+
+7. **Comment on issue with implementation details**
+
+**After Phase 3: Print "✓ Implementation complete. CONTINUING TO PHASE 4..." and IMMEDIATELY proceed.**
+
+**Before continuing, check for new comments** (see "Check for New Comments Between Phases" above).
+
+### Phase 4: Local Testing
+
+1. Determine which services need restart:
+   - `data-tamer-dashboard/` → Frontend (hot reload, NO restart needed)
+   - `tamer_service/` → `kubectl rollout restart deployment/tamer-datasource-consumer-dev deployment/tamer-message-consumer-dev -n datatamer`
+   - `consumer_service/` → `kubectl rollout restart deployment/consumer-service-dev -n datatamer`
+
+2. **Run Playwright headless tests:**
+```bash
+cd /home/riccardo/Documents/apps/datatamer/app/auto-ticket-logs
+node playwright-test.js login        # Test login works
+node playwright-test.js slides       # Test slides feature
+```
+Screenshots are saved to `/tmp/auto-ticket-screenshots/`
+
+3. If tests fail: Fix issues and re-test (do NOT move to production)
+
+4. If tests pass: Comment on issue and proceed
+
+**After Phase 4: Print "✓ Local tests passed. CONTINUING TO PHASE 5..." and IMMEDIATELY proceed.**
+
+**Before continuing, check for new comments** (see "Check for New Comments Between Phases" above).
+
+### Phase 5: Production Deployment
+
+1. **Deploy using git workflow:**
+```bash
+git push origin master
+git checkout production
+git merge master
+git push origin production
+git checkout master
+```
+
+2. **Wait for GitHub Actions:**
+```bash
+gh run watch -R data-tamer/<repo>
+```
+
+3. **Verify production pods:**
+```bash
+ssh root@153.92.127.95 'export KUBECONFIG=/etc/rancher/k3s/k3s.yaml && kubectl get pods -n datatamer | grep <service>'
+```
+
+4. Comment on issue with deployment status
+
+**After Phase 5: Print "✓ Production deployed. CONTINUING TO PHASE 6..." and IMMEDIATELY proceed.**
+
+**Before continuing, check for new comments** (see "Check for New Comments Between Phases" above).
+
+### Phase 6: Production Testing
+
+1. **Move ticket to "test" status and VERIFY:**
+```bash
+# Move to test
+gh project item-edit --id <item-id> --project-id PVT_kwDOCJIWbs4AnuSZ \
+  --field-id PVTSSF_lADOCJIWbs4AnuSZzgfaWGs \
+  --single-select-option-id c48bc058
+
+# Verify the change
+gh api graphql -f query='query { node(id: "<item-id>") { ... on ProjectV2Item { fieldValueByName(name: "Status") { ... on ProjectV2ItemFieldSingleSelectValue { name } } } } }' | jq -r '.data.node.fieldValueByName.name'
+```
+Print "✓ Ticket #<number> moved to test (verified)"
+
+2. **Run Playwright tests on production:**
+```bash
+cd /home/riccardo/Documents/apps/datatamer/app/auto-ticket-logs
+node playwright-test.js login --production
+node playwright-test.js slides --production
+```
+
+3. **Take final screenshot of the feature working:**
+   - Use browser automation (Claude in Chrome MCP) to navigate to the relevant page on production
+   - Take a screenshot showing the implemented feature
+   - Save to `/tmp/auto-ticket-screenshots/final-<issue-number>.png`
+
+4. **If production tests FAIL:**
+   - Comment on issue with failure details
+   - Rollback if critical
+   - Move ticket back to "Todo" (with verification)
+   - Stop workflow
+
+5. **If production tests PASS:**
+   - Comment on issue confirming success
+   - Print "✓ Production tests passed. CONTINUING TO PHASE 7..."
+
+**Before continuing, check for new comments** (see "Check for New Comments Between Phases" above).
+
+### Phase 7: Completion
+
+1. **Move ticket to "Done" and VERIFY:**
+```bash
+# Move to Done
+gh project item-edit --id <item-id> --project-id PVT_kwDOCJIWbs4AnuSZ \
+  --field-id PVTSSF_lADOCJIWbs4AnuSZzgfaWGs \
+  --single-select-option-id 98236657
+
+# Verify the change
+gh api graphql -f query='query { node(id: "<item-id>") { ... on ProjectV2Item { fieldValueByName(name: "Status") { ... on ProjectV2ItemFieldSingleSelectValue { name } } } } }' | jq -r '.data.node.fieldValueByName.name'
+```
+Print "✓ Ticket #<number> moved to Done (verified)"
+
+2. **Archive OpenSpec change:**
+```bash
+openspec archive "<change-name>"
+```
+
+3. **Upload final screenshot to GitHub:**
+   - Check if screenshot exists at `/tmp/auto-ticket-screenshots/final-<issue-number>.png`
+   - If exists, upload to GitHub using the issue comment with image attachment:
+```bash
+# Upload screenshot as asset and get URL
+SCREENSHOT="/tmp/auto-ticket-screenshots/final-<issue-number>.png"
+if [ -f "$SCREENSHOT" ]; then
+  # Create a gist or use GitHub's drag-drop equivalent via API
+  # For now, reference the local screenshot in the comment
+  gh issue comment <issue-number> -R data-tamer/<repo> --body "## Ticket Complete ✅
+
+### Final Result Screenshot
+![Final Result](https://app.datatamer.ai/screenshot-placeholder.png)
+
+*Screenshot saved locally at: \`$SCREENSHOT\`*
+
+### Summary
+All phases passed:
+- ✓ OpenSpec created
+- ✓ Implementation complete
+- ✓ Local tests passed
+- ✓ Production deployed
+- ✓ Production tests passed
+
+---
+*Automated by Claude Code Auto-Ticket Workflow*"
+fi
+```
+
+   **Alternative: Attach screenshot directly using gh CLI:**
+   - The `gh` CLI doesn't support direct image upload to comments
+   - Instead, use the Read tool to view the screenshot and describe the result in the comment
+   - Or upload to an image hosting service and include the URL
+
+4. **Add completion comment with screenshot description:**
+
+If screenshot was taken, use the Read tool to view it and include a description of what it shows in the completion comment. The comment should describe:
+- What page/feature is shown
+- Key visual elements confirming the fix works
+- Any notable UI changes
+
+```bash
+gh issue comment <issue-number> -R data-tamer/<repo> --body "## Ticket Complete ✅
+
+### Final Result
+<description of what the screenshot shows - the working feature on production>
+
+### Summary
+| Phase | Status |
+|-------|--------|
+| 0. Preflight | ✓ Complete |
+| 1. Discovery | ✓ Complete |
+| 2. OpenSpec | ✓ Created |
+| 3. Implementation | ✓ Committed |
+| 4. Local Testing | ✓ Passed |
+| 5. Production Deploy | ✓ Deployed |
+| 6. Production Testing | ✓ Passed |
+| 7. Completion | ✓ Done |
+
+---
+*Automated by Claude Code Auto-Ticket Workflow*"
+```
+
+5. **Close the issue:**
+```bash
+gh issue close <issue-number> -R data-tamer/<repo> --reason completed
+```
+
+Print "=== AUTO-TICKET WORKFLOW COMPLETE ===" with summary table.
+
+## Failure Handling
+
+When any phase fails:
+
+1. Comment on issue with failure details (phase, error, logs)
+2. **Move ticket back to "Todo" and VERIFY:**
+```bash
+gh project item-edit --id <item-id> --project-id PVT_kwDOCJIWbs4AnuSZ \
+  --field-id PVTSSF_lADOCJIWbs4AnuSZzgfaWGs \
+  --single-select-option-id f75ad846
+
+# Verify
+gh api graphql -f query='query { node(id: "<item-id>") { ... on ProjectV2Item { fieldValueByName(name: "Status") { ... on ProjectV2ItemFieldSingleSelectValue { name } } } } }' | jq -r '.data.node.fieldValueByName.name'
+```
+3. Report what went wrong
+
+## Login Credentials
+
+```
+Username: riccardo.ravaro@datatamer.ai
+Password: Nettuno1999
+```
+
+## Testing Environments
+
+### Local (app.local.datatamer.ai)
+- URL: https://app.local.datatamer.ai
+- DB access: `kubectl exec -it postgresql-0 -n datatamer -- psql -U postgres -d postgres`
+
+### Production (app.datatamer.ai)
+- URL: https://app.datatamer.ai
+- SSH: `ssh root@153.92.127.95`
+
+## Key Constraints
+
+1. **Fully automatic** - Never ask user for permission during execution
+2. **NO nested skills** - All logic is inlined to prevent workflow interruption
+3. **Verified status changes** - Every status transition is verified after execution
+4. **@claude tag required** - Only process tickets with `@claude` in body text
+5. **Sequential workflow** - Each ticket must pass each phase before proceeding
+
+---
+
+**Default Behavior**: When invoked, automatically process @claude tickets through the complete workflow. The ticket moves through statuses: Todo → In Progress → test → Done (verified at each step).
+
+---
+
+## Non-Interactive / Cron Mode
+
+```bash
+claude -p --dangerously-skip-permissions --output-format stream-json --verbose "/auto-ticket-workflow"
+```
+
+### Multi-Agent Mode
+
+```bash
+# Run parallel agents
+./run-multi-agent.sh 3
+
+# Cron entry
+* * * * * MAX_AGENTS=3 /path/to/auto-ticket-logs/run-multi-cron.sh
+```
+
+### Web UI
+
+```bash
+# View live logs at http://localhost:3847
+systemctl status auto-ticket-webui
+```

package/skills/auto-ticket.md

@@ -0,0 +1,67 @@
+# Auto-Ticket Workflow
+
+Process GitHub tickets with @claude tag through the full development lifecycle.
+
+Use the `auto-ticket-workflow` skill to:
+1. Find tickets in Todo with @claude tag
+2. Create OpenSpec proposal and implement
+3. Test locally and deploy to production
+4. Move ticket to Done when verified
+
+## GitHub CLI
+
+Use `agentdev gh` instead of `gh` for ALL GitHub operations.
+GH_TOKEN is pre-configured in your environment.
+
+Examples:
+- agentdev gh issue view 123 -R data-tamer/repo --json title,body,state,labels
+- agentdev gh api rest 'repos/data-tamer/repo/issues/123/comments' | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{JSON.parse(d).forEach(c=>console.log('---',c.user.login,c.created_at,'---\n'+c.body+'\n'))})"
+- agentdev gh issue comment 123 -R data-tamer/repo --body "update"
+- agentdev gh issue create -R data-tamer/repo --title "Fix" --body "description"
+- agentdev gh pr create -R data-tamer/repo --title "Fix" --body "..." --head fix-branch --base master
+- agentdev gh pr merge 45 -R data-tamer/repo --squash
+- agentdev gh issue reopen 123 -R data-tamer/repo
+
+## OpenSpec
+
+Use `agentdev openspec` instead of `openspec` for ALL spec-driven development operations.
+OpenSpec is bundled with agentdev — no separate install needed.
+
+Examples:
+- agentdev openspec init --tools claude-code
+- agentdev openspec status --json
+- agentdev openspec list --json
+- agentdev openspec validate --all --json
+- agentdev openspec instructions proposal --change my-change --json
+- agentdev openspec show my-change --json
+- agentdev openspec archive my-change --yes
+
+## Reading Ticket Comments (CRITICAL)
+
+Before implementing any ticket, ALWAYS read the full issue AND its comments:
+
+1. Read issue body: `agentdev gh issue view <N> -R data-tamer/<repo> --json title,body,state,labels`
+2. Read ALL comments: `agentdev gh api rest 'repos/data-tamer/<repo>/issues/<N>/comments' | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{JSON.parse(d).forEach(c=>console.log('---',c.user.login,c.created_at,'---\n'+c.body+'\n'))})"`
+
+Follow-up comments contain updated requirements that OVERRIDE the original ticket body.
+When a ticket is re-queued after completion, the latest comments explain what needs to change.
+Always prioritize the most recent @claude comment over the original issue body.
+
+## OpenSpec
+
+Use `agentdev openspec` instead of `openspec` for ALL spec-driven development operations.
+OpenSpec is bundled with agentdev — no separate install needed.
+
+Examples:
+- agentdev openspec init --tools claude-code
+- agentdev openspec status --json
+- agentdev openspec list --json
+- agentdev openspec validate --all --json
+- agentdev openspec instructions proposal --change my-change --json
+- agentdev openspec show my-change --json
+- agentdev openspec archive my-change --yes
+
+Workflow: After claiming a ticket, create an OpenSpec proposal before implementing.
+Use `agentdev openspec status --json` to check artifact completion during the workflow.
+
+Run the skill now and report progress.