Forgekeeper Task Card

Forgekeeper Task Card Creation

Overview

This skill helps create well-structured task cards for the Forgekeeper project following the established conventions in tasks.md.

When to Use

Use this skill when:

• User requests creating a new task or feature
• Planning new development work
• Need to document a bug fix or improvement
• Creating sprint or milestone tasks

Prerequisites

• Access to tasks.md file (read to understand existing structure)
• Understanding of the feature being requested
• Sprint/milestone context (if applicable)

Instructions

Step 1: Identify Task Details

Gather the following information:

• Task ID: Next available T### number (read tasks.md to find latest)
• Sprint/Milestone: Which sprint or milestone this belongs to
• Task Type: feat, fix, chore, docs, test, refactor
• Title: Clear, concise description (< 80 characters)
• Description: Detailed explanation of what needs to be done

Step 2: Structure the Task Card

Follow this template:

### T### - [Title]

**Type**: [feat/fix/chore/docs/test/refactor]
**Sprint**: [Sprint name or number]
**Status**: [pending/in-progress/completed]
**Priority**: [high/medium/low]

**Description**:
[Detailed description of the task]

**Acceptance Criteria**:
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

**Technical Notes**:
- Implementation approach
- Files to modify
- Dependencies or prerequisites

**Testing**:
- [ ] Unit tests
- [ ] Integration tests
- [ ] Manual testing steps

**Documentation**:
- [ ] Update CLAUDE.md if architecture changes
- [ ] Add/update comments
- [ ] Update relevant docs/

**Estimated Effort**: [hours or story points]

Step 3: Validate Against Project Standards

Ensure the task card:

• Uses conventional commit prefixes (feat:, fix:, docs:, etc.)
• Includes all required sections
• Has clear acceptance criteria
• Specifies testing requirements
• Notes documentation needs

Step 4: Place in Appropriate Milestone

Tasks should be organized under:

• Active Sprints: Current development work
• Backlog: Future work, not yet prioritized
• Completed: Finished tasks (moved to bottom)

Expected Output

A complete task card entry that can be added to tasks.md, properly formatted and containing all necessary information for implementation.

Error Handling

Error: Missing task ID

• Cause: Haven't read tasks.md to find next available number
• Fix: Read tasks.md and find the highest T### number, increment by 1

Error: Unclear acceptance criteria

• Cause: Task requirements not well defined
• Fix: Ask user for clarification on expected outcomes

Error: Missing sprint/milestone

• Cause: Task not associated with development plan
• Fix: Ask user which sprint or add to Backlog

Examples

Example 1: Feature Request

User request: "Add support for PostgreSQL connections in MCP"

Skill invocation:
1. Read tasks.md to find next ID (e.g., T415)
2. Identify as Sprint 4 task (Custom MCP Servers)
3. Create task card:

### T415 - Add PostgreSQL MCP Server Support

**Type**: feat
**Sprint**: Sprint 4 - Custom MCP Servers
**Status**: pending
**Priority**: medium

**Description**:
Add support for PostgreSQL database connections through a custom MCP server.
Users should be able to query databases, view schemas, and execute operations.

**Acceptance Criteria**:
- [ ] Create postgres-mcp-server in frontend/mcp/servers/
- [ ] Implement query execution tool
- [ ] Implement schema inspection tool
- [ ] Add connection pooling
- [ ] Handle connection errors gracefully

**Technical Notes**:
- Use pg library for PostgreSQL connections
- Follow MCP server protocol v1.0
- Support connection string from environment variable
- Implement query timeout (30s default)

**Testing**:
- [ ] Unit tests for query execution
- [ ] Integration tests with test database
- [ ] Error handling tests (connection failures, timeouts)
- [ ] Manual testing with local PostgreSQL

**Documentation**:
- [ ] Add to docs/mcp/PRE_BUILT_SERVERS.md
- [ ] Create example config in mcp-servers.example.json
- [ ] Update CLAUDE.md with Postgres server info

**Estimated Effort**: 8 hours

Example 2: Bug Fix

User request: "Fix hot-reload not working for skills"

Skill invocation:
1. Read tasks.md to find next ID (e.g., T508)
2. Identify as Sprint 3 task (Skills System)
3. Create task card:

### T508 - Fix Skills Hot-Reload File Watching

**Type**: fix
**Sprint**: Sprint 3 - Skills System
**Status**: pending
**Priority**: high

**Description**:
File watching for skills hot-reload is not triggering when SKILL.md files
are modified. Need to debug and fix the file watcher in skills/registry.mjs.

**Acceptance Criteria**:
- [ ] File watcher detects changes to SKILL.md files
- [ ] Debounce works correctly (500ms delay)
- [ ] Skills reload when files change
- [ ] No duplicate reload triggers
- [ ] Works on Linux, macOS, and Windows

**Technical Notes**:
- Issue likely in skills/registry.mjs startWatcher()
- Check fs.watch vs fs.watchFile behavior
- May need recursive:true option
- Test with both file edits and new file creation

**Testing**:
- [ ] Unit test for watcher setup
- [ ] Integration test: modify skill, verify reload
- [ ] Test on multiple platforms
- [ ] Test with multiple rapid changes (debounce)

**Documentation**:
- [ ] Add troubleshooting section to docs/skills/README.md
- [ ] Document platform-specific watcher behavior

**Estimated Effort**: 3 hours

Resources

• tasks.md - Main task tracking file
• .git/logs/HEAD - For commit message examples
• CONTRIBUTING.md - Contribution guidelines

Notes

• Always read tasks.md first to understand current task numbering and structure
• Keep tasks focused and atomic (one clear objective)
• Link related tasks using "Depends on: T###" if needed
• Update task status as work progresses (pending → in-progress → completed)
• Move completed tasks to "Completed" section with completion date

Version History

• 1.0.0 (2025-11-21): Initial release