br4zz4:spec

Guides structured dialogue to write and approve technical specification documents.

Updated May 25, 2025
One-click install
npx skills add https://github.com/oporpino/commons --skill br4zz4-spec-oporpino
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: br4zz4:spec
Source: https://github.com/oporpino/commons/tree/main/ai/shared/skills/br4zz4%3Aspec
Command: npx skills add https://github.com/oporpino/commons --skill br4zz4-spec-oporpino

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? It prevents premature implementation by enforcing a structured specification workflow: explore context, dialogue with the user, propose approaches, write the spec, and get explicit approval before any code is written. ## Core Features & Use Cases - Phased specification workflow: Explores project docs and git history, infers related Asana tasks, asks one question at a time, and proposes 2-3 approaches with trade-offs. - Standardized spec output: Writes timestamped Markdown specs to .project/docs/specs/ with Portuguese body, English frontmatter, status tracking, and commits them to git. - Optional visual companion: Starts a local browser server to present layout or architecture options as clickable HTML mockups when decisions are visual. - Use Case: A developer wants to add a new feature. The skill walks them through understanding the problem, comparing implementation approaches, writing an approved spec, and handing off to the planning skill. ## Quick Start Ask the assistant to plan and document a change before implementing it, then answer its questions one at a time until the spec is written and approved.

Frequently Asked Questions about br4zz4:spec

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a technical spec before implementing a feature?▼

Invoke the spec skill and answer its questions one at a time. It explores your project docs and git history, proposes 2-3 approaches with trade-offs, then writes a timestamped Markdown spec to .project/docs/specs/ and commits it after your approval.

What is the workflow for planning a code change with AI assistance?▼

The workflow is: explore context, link an Asana task, dialogue to understand the problem, propose approaches, write and self-review the spec, get explicit approval, then hand off to the plan skill. No code is written until the spec is approved.

Can the spec skill create Asana tasks automatically?▼

It searches for related Asana tasks using asana_search_tasks based on the product inferred from your working directory. It only creates a new task after you explicitly confirm, and never asks you for a task ID.

When should I use the visual companion for spec decisions?▼

Use it only for genuinely visual questions like UI layouts, wireframes, or architecture diagrams. It starts a local server rendering HTML option fragments in the browser. Conceptual or trade-off questions stay in the terminal.

What are the limitations of the spec skill?▼

It never writes code, creates branches, or implements anything. Over-scoped requests spanning multiple subsystems are flagged for decomposition first, and specs must be written fresh rather than overwriting previous ones.