diff --git a/skills/complete-card/SKILL.md b/skills/complete-card/SKILL.md index de6acd9..4ad8c2d 100644 --- a/skills/complete-card/SKILL.md +++ b/skills/complete-card/SKILL.md @@ -1,45 +1,12 @@ -# Complete Card - -Mark a card as done by updating its status field to `done` and setting the updated timestamp. This replaces the old ticket archival system where tickets were moved to an `.archived/` directory. - -## When to Use - -Mark a card complete when: -- A Phase addressing the card's work has been completed and reviewed -- The work item has been fully implemented and verified -- The Overseer determines the card's requirements are satisfied - -## Status Update - -Cards track their lifecycle state in the `status` frontmatter field: -- `todo`: Not yet started (default for new cards) -- `backlog`: Deprioritized or deferred -- `in-progress`: Currently being worked on -- `done`: Completed and closed - -Completing a card means setting `status: done`. - -## Timestamp Update - -When marking a card complete, also update the `updated` field to the current UTC time in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` +--- +name: complete-card +description: "Mark a Hieroglyphs-compatible card as done by updating its status and timestamp in `.ushabti/cards/{slug}/card.md`. Use when a Phase addressing the card has been completed and reviewed by the Overseer." +user-invocable: false +--- -Example: `2026-02-08T14:30:00Z` - -Generate timestamp: -```bash -date -u +"%Y-%m-%dT%H:%M:%SZ" -``` - -## Frontmatter Preservation - -**CRITICAL**: When updating a card, you MUST preserve all existing frontmatter fields, including fields you don't recognize. Hieroglyphs may add additional fields that agents don't know about. Dropping unknown fields will corrupt the card. +# Complete Card -Strategy: -1. Read the entire card file -2. Parse the frontmatter section -3. Update only the `status` and `updated` fields -4. Write back the complete frontmatter with all original fields intact -5. Preserve the markdown body unchanged +Mark a card as done by updating its `status` field to `done` and setting the `updated` timestamp. Completed cards remain in `.ushabti/cards/` as historical record — they are not moved or deleted. ## Procedure @@ -47,52 +14,26 @@ Strategy: 2. **Read card**: Load entire file contents 3. **Parse frontmatter**: Extract YAML frontmatter section (between `---` delimiters) 4. **Update status**: Change `status` field to `done` -5. **Update timestamp**: Set `updated` field to current UTC time -6. **Preserve alphabetical order**: Keep frontmatter fields sorted alphabetically -7. **Write back**: Replace card.md with updated content +5. **Update timestamp**: Set `updated` field to current UTC time in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) +6. **Preserve all fields**: Keep all existing frontmatter fields in alphabetical order, including unknown fields added by Hieroglyphs +7. **Write back**: Replace card.md with updated content, preserving the markdown body unchanged 8. **Verify**: Confirm status and updated fields changed -## Example Implementation - -```bash -slug="improve-error-handling" -card_path=".ushabti/cards/${slug}/card.md" - -# Verify card exists -if [ ! -f "$card_path" ]; then - echo "Error: Card not found: $card_path" - exit 1 -fi - -# Generate new timestamp -timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ") - -# Read current card -current_content=$(cat "$card_path") - -# Update status and timestamp using sed -# This example assumes frontmatter is well-formed -updated_content=$(echo "$current_content" | sed "s/^status: .*/status: done/" | sed "s/^updated: .*/updated: ${timestamp}/") - -# Write back -echo "$updated_content" > "$card_path" - -echo "Card ${slug} marked as done" -``` +## Frontmatter Preservation (CRITICAL) -## Safe Update with awk +When updating a card, you MUST preserve all existing frontmatter fields, including fields you don't recognize. Hieroglyphs may add additional fields that agents don't know about. Dropping unknown fields will corrupt the card. -For more robust parsing that preserves unknown fields: +## Example ```bash -slug="example-card" +slug="improve-error-handling" card_path=".ushabti/cards/${slug}/card.md" timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ") # Create temporary file temp_file=$(mktemp) -# Update frontmatter while preserving structure +# Update frontmatter while preserving all fields and structure awk -v ts="$timestamp" ' BEGIN { in_frontmatter=0; first_delimiter=0 } /^---$/ { @@ -105,41 +46,22 @@ awk -v ts="$timestamp" ' { print } ' "$card_path" > "$temp_file" -# Replace original mv "$temp_file" "$card_path" +echo "Card ${slug} marked as done" ``` ## Verification -After updating, verify the changes: - ```bash -# Check status field grep '^status:' "$card_path" # Expected: status: done -# Check updated timestamp grep '^updated:' "$card_path" # Expected: updated: - -# Verify frontmatter is still valid YAML -sed -n '/^---$/,/^---$/p' "$card_path" | sed '1d;$d' ``` -## Common Issues - -**Issue**: Frontmatter order changes during update -**Solution**: Manually restore alphabetical order or use YAML-aware tools - -**Issue**: Unknown fields dropped during update -**Solution**: Parse more carefully, preserving all fields not explicitly updated - -**Issue**: Markdown body corrupted -**Solution**: Only modify the frontmatter section; everything after the closing `---` should remain unchanged - ## Notes -- Completed cards remain in `.ushabti/cards/` (they are NOT moved to a separate directory) - Cards with `status: done` should be excluded from "open work" listings -- The `updated` timestamp tracks the last modification time (creation, status change, or any other update) -- Never delete cards—they serve as historical record of work items +- The `updated` timestamp tracks the last modification time +- Never delete cards — they serve as historical record of work items diff --git a/skills/create-card/SKILL.md b/skills/create-card/SKILL.md index 1a49a8c..fe2faa0 100644 --- a/skills/create-card/SKILL.md +++ b/skills/create-card/SKILL.md @@ -1,123 +1,47 @@ -# Create Card - -Create a new Hieroglyphs-compatible card to track work items, bugs, or features. Cards use the Hieroglyphs format with YAML frontmatter and markdown body, stored in `.ushabti/cards/{slug}/card.md` directories. - -## When to Use - -Create a card when: -- Discovering technical debt that should be tracked -- Identifying a bug or issue that should be addressed later -- Capturing a feature request or improvement idea -- Recording any work item that should be tracked separately from the current Phase - -## Card Schema - -Cards MUST have these frontmatter fields in **alphabetical order**: - -- `created`: ISO 8601 timestamp (e.g., `2026-02-08T14:30:00Z`) -- `id`: UUID v4 (generated via `uuidgen` command) -- `priority`: One of `low`, `medium`, `high` -- `slug`: Lowercase kebab-case identifier matching directory name -- `status`: One of `todo`, `backlog`, `in-progress`, `done` -- `tags`: Array of strings (may be empty: `[]`) -- `title`: Human-readable card title -- `type`: One of `bug`, `feature` -- `updated`: ISO 8601 timestamp (same as `created` when first created) - -## Slug Derivation - -The slug is derived from the title: -1. Convert to lowercase -2. Replace spaces with hyphens -3. Remove all punctuation except hyphens -4. Collapse multiple consecutive hyphens to single hyphen -5. Strip leading and trailing hyphens - -Examples: -- "Fix error handling" → `fix-error-handling` -- "Add user guide agent!" → `add-user-guide-agent` -- "Bug: broken validation" → `bug-broken-validation` - -## Directory Structure - -Cards are stored in directories named after their slug: - -``` -.ushabti/cards/{slug}/card.md -``` - -Before creating a card, verify the directory doesn't already exist to prevent slug collisions. - -## File Format - -Card files use YAML frontmatter delimited by `---`, followed by markdown content: - -```markdown --- -created: 2026-02-08T14:30:00Z -id: 550e8400-e29b-41d4-a716-446655440000 -priority: medium -slug: improve-error-handling -status: todo -tags: [] -title: Improve error handling -type: feature -updated: 2026-02-08T14:30:00Z +name: create-card +description: "Create a new Hieroglyphs-compatible card in `.ushabti/cards/{slug}/card.md` with UUID, YAML frontmatter, and markdown body. Use when capturing work items, bugs, or features outside the current Phase." +user-invocable: false --- -# Overview - -Current error handling is inconsistent across agents. Some failures -are silent, making debugging difficult. - -# Requirements +# Create Card -- Define standard error response format -- Update all agents to use consistent error handling -- Add error recovery examples to documentation -``` +Create a new Hieroglyphs-compatible card to track work items, bugs, or features. Cards are stored in `.ushabti/cards/{slug}/card.md` with YAML frontmatter and markdown body. ## Procedure 1. **Validate inputs**: Ensure title, priority, and type are provided -2. **Derive slug**: Apply slug derivation rules to title +2. **Derive slug**: Lowercase the title, replace spaces with hyphens, remove punctuation, collapse consecutive hyphens 3. **Check for collisions**: Verify `.ushabti/cards/{slug}/` doesn't exist -4. **Generate UUID**: Run `uuidgen` command (lowercase the output) -5. **Get timestamp**: Generate current UTC time in ISO 8601 format: `date -u +"%Y-%m-%dT%H:%M:%SZ"` +4. **Generate UUID**: Run `uuidgen | tr '[:upper:]' '[:lower:]'` +5. **Get timestamp**: `date -u +"%Y-%m-%dT%H:%M:%SZ"` 6. **Create directory**: `mkdir -p .ushabti/cards/{slug}/` -7. **Write card.md**: Create file with frontmatter and markdown body -8. **Verify**: Ensure all frontmatter fields are present and alphabetically ordered - -## Validation Checklist - -Before completing card creation, verify: -- [ ] All nine required frontmatter fields are present -- [ ] Frontmatter fields are in alphabetical order -- [ ] `id` is a valid UUID (lowercase) -- [ ] `created` and `updated` are ISO 8601 timestamps -- [ ] `status` is `todo` (default for new cards) -- [ ] `priority` is one of `low`, `medium`, `high` -- [ ] `type` is one of `bug`, `feature` -- [ ] `slug` matches directory name exactly -- [ ] Markdown body has Overview and Requirements sections -- [ ] Directory `.ushabti/cards/{slug}/` exists and contains `card.md` +7. **Write card.md**: Create file with all nine frontmatter fields in alphabetical order plus markdown body +8. **Verify**: Ensure all fields present, alphabetically ordered, slug matches directory name + +## Required Frontmatter Fields (alphabetical order) + +| Field | Type | Values | +|-------|------|--------| +| `created` | string | ISO 8601 timestamp | +| `id` | string | UUID v4 (lowercase) | +| `priority` | string | `low`, `medium`, `high` | +| `slug` | string | kebab-case, matches directory name | +| `status` | string | `todo` (always for new cards) | +| `tags` | array | strings (empty `[]` for now) | +| `title` | string | human-readable title | +| `type` | string | `bug`, `feature` | +| `updated` | string | ISO 8601 timestamp (same as `created` initially) | ## Example -Creating a card with title "Add user guide agent", priority "low", type "feature": - ```bash -# Derive slug slug="add-user-guide-agent" - -# Generate UUID and timestamp id=$(uuidgen | tr '[:upper:]' '[:lower:]') timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ") -# Create directory mkdir -p ".ushabti/cards/${slug}/" -# Write card.md cat > ".ushabti/cards/${slug}/card.md" <