agentleFS
omidnwomidnw/my-skills/skills/design-to-delivery/SKILL.md

design-to-delivery

Skill0 starsChanged 13 days agoMITView on GitHub

Recommend a diagram → brainstorming → specs → tasks workflow for complex feature, screen, API or architecture design, or use it when explicitly requested. Provides editable Excalidraw artifacts and timed documentation. Adapt or simplify the process to the task; ordinary design requests do not require a full package. Capability skills supply domain details.

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. About 0 are common, 7 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Consider this skill when design spans multiple screens/services, has substantial state/permission branching, changes contracts or …

    line 19
  2. Distinctive:

    Read project instructions, existing documentation, affected source, callers, contracts and relevant tests.

    line 41
  3. Very specific:

    Read references/artifact-templates.md before writing these artifacts.

    line 54
  4. Very specific:

    Prefer an editable diagram first when it clarifies the flow: Use excalidraw when producing this artifact.

    line 56
  5. Very specific:

    Brainstorm from the saved diagram: Read its labels and connections using structured extraction.

    line 65
  6. Very specific:

    Write specs.md: After the leading metadata, the first content link is the relative link to the Excalidraw diagram.

    line 73
  7. Distinctive:

    Read each target before edits.

    line 92
  8. Distinctive:

    Update statuses and timestamps at actual transitions.

    line 93
  9. Very specific:

    Read the real clock at creation, updates, starts, pauses, resumes and completion.

    line 104
  10. Very specific:

    Use ISO 8601 with a timezone offset (default Asia/Tehran, unless the project or user specifies another).

    line 105
  11. Very specific:

    Prefer starting generated workflow Markdown artifacts with metadata containing created_at, updated_at, completed_at and status.

    line 107
  12. Distinctive:

    Use per-task start/end and pause/resume events.

    line 112
  13. Distinctive:

    Keep an append-only event/change ledger: timestamp, task/requirement ID, user visible outcome or decision, evidence and status.

    line 120
  14. Distinctive:

    Check the artifacts actually selected/requested.

    line 136

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Design to delivery

Purpose

Make the design and delivery path explicit and traceable: inspect → diagram → brainstorm → specification → tasks → authorized implementation → verification. Preserve all existing instructions, diagrams, specs and task history.

When to use

Consider this skill when design spans multiple screens/services, has substantial state/permission branching, changes contracts or architecture, or needs durable handoff documentation. Also use it when the user explicitly requests this workflow. This skill coordinates the suggested artifact sequence; user-behavior-flow, api-behavior-flow, design-principles and architecture-and-performance are domain companions. Standalone diagrams, audits, trivial edits and routine bug fixes do not automatically require this full sequence.

Judgment and proportionality

This is a recommended playbook for complex work, not a mandatory gate. Following it helps prevent missing error states, inconsistent contracts, implementation drift and verification gaps; it reduces risk without guaranteeing bug-free work. Choose the parts that materially help the current task. Combine documents, iterate diagram and spec together, or use a simpler evidence-based method when that is clearer. Do not generate unnecessary artifacts, invent alternative designs or wait for approval just to satisfy a checklist. Keep the user's actual deliverables, project constraints and authorized scope. If the user explicitly asks for diagrams/specs/tasks or timing fields, deliver those requested artifacts. Explain a material adaptation briefly when it affects a requested deliverable. Confidentiality, preservation of existing work and truthful evidence still apply.

Preconditions

Read project instructions, existing documentation, affected source, callers, contracts and relevant tests. Identify scope, authorization and real tools. Project-specific content conventions remain applicable; an explicit current user request wins on paths or format. Keep work material and rendering local.

Suggested workflow

  1. Inspect and establish a work ID. Reuse the existing feature's ID and docs when improving it. For new work choose a descriptive collision-free slug, prefixed with the actual creation date if useful. Use the same ID throughout:
    • docs/diagrams/<work-id>.excalidraw.json
    • docs/diagrams/<work-id>.metadata.md
    • docs/specs/<work-id>/specs.md
    • docs/task/<work-id>/tasks.md (singular task, as requested). Read references/artifact-templates.md before writing these artifacts. Never overwrite another feature or rename/move old documents to fit this layout.
  2. Prefer an editable diagram first when it clarifies the flow. Use excalidraw when producing this artifact. Map actors, entry points, actions, decisions, states, exits and relevant API/service boundaries from inspected evidence. Include important failure and permission paths. For UI design include screen hierarchy/wireflow; for architecture include dependency direction. Label assumptions and unresolved branches. Run the Excalidraw validator. The default is to save the actual diagram before drafting the spec; iterate or change this order when the task benefits from it. Structural validation is not visual verification. Use a local preview when available; otherwise record visual verification as not run.
  3. Brainstorm from the saved diagram. Read its labels and connections using structured extraction. Load actual Superpowers brainstorming when available; otherwise perform this documented local step and identify the fallback honestly. Compare plausible alternatives and tradeoffs, find missing/error states, and record a chosen approach with reasons and explicit open questions. Preserve evidence of rejected alternatives. Refine and revalidate the diagram before writing the specification. Do not invent multiple alternatives where an established contract already determines the answer.
  4. Write specs.md. After the leading metadata, the first content link is the relative link to the Excalidraw diagram. Include the metadata companion and task ledger links too. Record scope/non-goals, actors, requirements with stable IDs, selected approach and alternatives, flows and states, applicable UI/RTL/accessibility rules, contracts/layers, acceptance criteria, verification cases, risks and unresolved questions. Use the appropriate domain skills; put their flow detail in this spec or linked existing flow documents without erasing them or maintaining competing copies. Give important diagram nodes and spec requirements stable labels/IDs for traceability.
  5. Derive tasks from the spec. Load actual Superpowers writing-plans when available. Write the ordered phases and tasks to tasks.md, with spec and diagram links immediately after metadata. Each task has an ID, requirement references, dependencies, expected files/boundaries, result, verification method, status, timing and evidence. Include appropriate unit/API/E2E and rendered UI checks; use existing project testing conventions. Resolve real blockers, but do not add a new approval ceremony for authorized work.
  6. Execute only the requested scope. A design-only request delivers the selected or explicitly requested design artifacts; implementation stays planned with no invented completion timestamp. An implementation request continues through the ledger. Read each target before edits; use the relevant engineering/testing skills. Update statuses and timestamps at actual transitions. Changes in requirements update the diagram, spec and impacted tasks together; preserve the prior rationale/history. Revalidate changed diagrams before dependent code changes.
  7. Verify and close honestly. Attach actual check results to acceptance criteria and task IDs. Mark a task done only after its requested result exists and its required verification succeeds. Record failures, skips and not-run checks distinctly. Close the whole implementation ledger only when all required work is complete; blocked work remains blocked. Design artifacts can finish while implementation tasks remain planned. Report the artifact links.

Documentation conventions when using this workflow

  • Read the real clock at creation, updates, starts, pauses, resumes and completion. Use ISO 8601 with a timezone offset (default Asia/Tehran, unless the project or user specifies another). Never guess or backdate timestamps.
  • Prefer starting generated workflow Markdown artifacts with metadata containing created_at, updated_at, completed_at and status. Keep creation immutable; use null for an event that has not occurred. updated_at changes only on a real edit.
  • Excalidraw is JSON: never prepend Markdown/YAML. The linked .metadata.md companion owns the same timing fields and records diagram changes.
  • Use per-task start/end and pause/resume events. Calendar elapsed time and recorded active work are different metrics; only compute active time from complete measured intervals. If intervals are incomplete, mark it unknown. These are observed workflow times, not a claim to measure model reasoning or tool CPU time. Do not infer duration from file modification times.
  • On reopening, preserve the previous completion event, clear current completed_at, record the reason and open a new timed interval. Never erase earlier task rows, decisions or evidence to make history look clean.
  • Keep an append-only event/change ledger: timestamp, task/requirement ID, user visible outcome or decision, evidence and status. Derive changelog entries only from verified implemented outcomes; planned ideas are not releases. Updating/publishing a release changelog still follows the requested scope.
  • Selected/requested documentation is a persistent deliverable, so internal-planning rules do not suppress it. It does not require routine narration, authorize production writes/commits or authorize external disclosure.

Common mistakes

Treating this playbook as mandatory for simple work; decorative diagrams that do not describe the flow; losing important decisions before implementation; deleting an older spec; placeholders presented as dates; marking all tasks finished after design alone; calculating active time from a single start/end despite pauses; treating a valid JSON file as a visually verified diagram; conflicting copies of the same contract.

Validation

  • Check the artifacts actually selected/requested; omitted optional artifacts are not failures. Preserve explicit user requirements and report relevant gaps.
  • The editable diagram exists and its structural validator succeeds; visual verification has explicit evidence or a not-run status.
  • Brainstorming decisions refer to the saved diagram; the chosen flow matches the spec. The spec's first content link points to the diagram.
  • Relative links resolve; IDs connect diagram → requirements → tasks → checks.
  • Metadata uses actual offset timestamps, stable creation times and honest completion states. Every task has a result and verification plan.
  • The event history supports timing and future changelog extraction without deleting prior content or exposing work material externally.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.