dev.speculate_skill

Overview

This skill provides continuous project context using the Speculate documentation framework. It ensures agents always initialize, read, and reference a consistent set of docs (coding rules, shortcuts, templates, and project specs) so work follows the project's structure and standards. Use it automatically for every task to maintain code quality and workflow consistency.

How this skill works

On first use it checks for docs/docs-overview.md and runs an install script to populate the docs/ tree if missing. Before any change it instructs agents to read docs/docs-overview.md, then docs/development.md, and finally relevant rules and active specs under docs/general/ and docs/project/. It also provides explicit path resolution for @-prefixed references and recommends update and install scripts to sync the canonical rules while preserving local customizations.

When to use it

• Before starting any coding task or design change in the repository
• When onboarding a new agent or human to the codebase
• Before writing tests, creating a new feature spec, or updating architecture docs
• During pre-commit checks and PR preparation to enforce project rules
• When you need to resolve rules, shortcuts, or path conventions for the project

Best practices

• Always read docs/docs-overview.md first to discover applicable rules and shortcuts
• Run the install script if docs/ is missing, then update docs/development.md with project specifics
• Follow the Speculate path convention: resolve @-prefixed paths relative to project root
• Use the provided shortcuts for planning, implementation, commits, and PRs to keep workflows consistent
• Keep docs/project/specs/active/ updated for ongoing work and archive finished specs to specs/done/

Example use cases

• Initialize documentation for a fresh repository so agents have a canonical ruleset
• Create a new feature: follow @shortcut:new-plan-spec.md then implement with @shortcut:implement-spec.md
• Run pre-commit validation by referencing @shortcut:precommit-process.md and commit guidance
• Onboard an agent to follow TypeScript rules and testing practices documented in docs/general/
• Document a new system flow in docs/project/flows/ so future agents can reproduce the lifecycle