Skip to content

feat: improve skill scores for ushabti card skills #16

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rohan-tessl wants to merge 1 commit into
base: master
Choose a base branch
from
Open

feat: improve skill scores for ushabti card skills #16

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 18 additions & 96 deletions skills/complete-card/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,98 +1,39 @@
# 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

1. **Verify card exists**: Check that `.ushabti/cards/{slug}/card.md` exists
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 }
/^---$/ {
Expand All @@ -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: <current timestamp>

# 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
138 changes: 35 additions & 103 deletions skills/create-card/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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" <<EOF
---
created: ${timestamp}
Expand All @@ -141,9 +65,17 @@ updated: ${timestamp}
EOF
```

## Validation Checklist

- All nine required frontmatter fields present and alphabetically ordered
- `id` is a valid lowercase UUID
- `created` and `updated` are ISO 8601 timestamps
- `status` is `todo`
- `slug` matches directory name exactly
- Markdown body has Overview and Requirements sections

## Notes

- New cards always start with `status: todo`
- The `tags` field is reserved for future use; use empty array for now
- Cards with `status: done` are considered closed (use `complete-card` skill to update status)
- Unknown frontmatter fields MUST be preserved when updating cards (Hieroglyphs may add fields agents don't know about)
- Cards with `status: done` are considered closed (use `complete-card` skill)
- Unknown frontmatter fields MUST be preserved when updating cards (Hieroglyphs may add fields)
Loading