dev.speculate

This skill provides comprehensive project context through the Speculate documentation framework. It ensures agents always have access to coding rules, development workflows, and project structure.

Automatic Initialization

IMPORTANT: Before working on any task, check if the Speculate docs are initialized. Look for docs/docs-overview.md in the current project. If it doesn't exist, initialize now using the install script

node ~/.claude/skills/dev.speculate/scripts/install.js

This copies the complete Speculate documentation structure to docs/:

• docs/docs-overview.md - Overview of all documentation
• docs/development.md - Project development workflows (you'll need to customize this)
• docs/general/ - Cross-project rules, shortcuts, templates
• docs/project/ - Project-specific specs, architecture, research

Reading Project Context

Always read docs/docs-overview.md first before starting any task.

The docs-overview provides:

• Navigation to all coding rules (TypeScript, Python, testing, etc.)
• Available shortcuts for common workflows
• Project structure and documentation layout
• Links to project-specific specs and architecture

Path Convention

IMPORTANT: Throughout the Speculate documentation, paths prefixed with @ indicate paths from the project root.

For example:

• @docs/general/agent-rules/python-rules.md → docs/general/agent-rules/python-rules.md
• @shortcut:implement-spec.md → docs/general/agent-shortcuts/shortcut:implement-spec.md

When you see these @docs/... or @shortcut:... references in the documentation, resolve them relative to the project root directory.

Reading Strategy

1. Start with overview: Read docs/docs-overview.md to understand available documentation
2. Check development setup: Read docs/development.md for build/test/lint workflows
3. Load relevant rules: Based on the task, read specific rules from docs/general/agent-rules/
4. Check active specs: Look in docs/project/specs/active/ for related work
5. Use shortcuts: Reference shortcuts from docs/general/agent-shortcuts/ for structured workflows

Key Documentation Files

After initialization, these files are available:

Essential Docs:

• docs/docs-overview.md - Start here! Overview of all documentation
• docs/development.md - Project setup, build, test, lint workflows

General Rules (in docs/general/agent-rules/):

• general-coding-rules.md - Universal coding standards
• general-testing-rules.md - Testing best practices
• typescript-rules.md - TypeScript-specific rules
• python-rules.md - Python-specific rules
• convex-rules.md - Convex database rules
• And more language/framework specific rules

Shortcuts (in docs/general/agent-shortcuts/):

• shortcut:new-plan-spec.md - Create feature planning document
• shortcut:implement-spec.md - Implement from specification
• shortcut:commit-code.md - Pre-commit validation workflow
• shortcut:create-pr-*.md - Pull request workflows
• And more task-specific shortcuts

Project Docs (in docs/project/):

• specs/active/ - Current feature specifications
• specs/done/ - Completed specs (historical reference)
• architecture/ - System design documentation
• flows/ - System flows documentation
• research/ - Technical research notes

A note on flows. A flow is a like a mini architecture doc that describes the lifecycle of a behavior in the code base. For example, bootstraping a system could be a flow. The lifecylce of a particular API request could be another. Flows are meant to help llms and humans quickly recapture context on a particular part of the code.

Updating Documentation

To sync with the latest Speculate documentation:

node ~/.claude/skills/dev.speculate/scripts/update.js

This updates the docs/general/ folder while preserving:

• Your docs/development.md
• Your project-specific docs in docs/project/
• Any local customizations

Workflow Integration

Before Every Task

1. Check if docs are initialized (run install.js if needed)
2. Read docs/docs-overview.md for context
3. Read docs/development.md for build/test workflows
4. Identify relevant rules and shortcuts for the task

During Development

• Follow coding rules from docs/general/agent-rules/
• Use shortcuts for structured workflows (planning, implementation, commits, PRs)
• Create specs in docs/project/specs/active/ for new features
• Document architecture decisions in docs/project/architecture/
• Document new flows in docs/project/flows/

For Spec-Driven Development

Use the structured workflow:

1. Plan: Use @shortcut:new-plan-spec.md to create a feature plan
2. Design: Use @shortcut:new-implementation-spec.md for implementation details
3. Implement: Follow @shortcut:implement-spec.md with TDD approach
4. Validate: Use @shortcut:precommit-process.md before committing
5. Commit: Use @shortcut:commit-code.md for structured commits
6. PR: Use @shortcut:create-pr-*.md for pull requests

Customizing for Your Project

After initialization:

1. Edit docs/development.md: Update with your project's specific:

   • Build commands
   • Test commands
   • Lint/format commands
   • Deployment workflows

2. Add project specs: Create specifications in docs/project/specs/active/

3. Document architecture: Add design docs to docs/project/architecture/

4. Research notes: Store technical investigations in docs/project/research/

Benefits

This framework ensures:

• Consistent quality - Agents follow defined coding standards
• Structured workflows - Clear processes for planning, implementing, validating
• Project context - Agents understand your codebase and workflows
• Sustainable code - Avoid "slop code" through spec-driven development
• Knowledge retention - Specs and architecture docs preserve decisions

Notes

• The install/update scripts preserve your customizations in docs/development.md and docs/project/
• If you don't have a docs/development.md, create one from the sample template
• The docs/general/ folder gets updated when you run update.js