Skip to content

jeremylongshore/tons-of-skills-marketplace / plugins/ai-agency/hyperflow/skills/hyperflow

hyperflow

Flagged

Use when applying Hyperflow's orchestration doctrine in Codex, Antigravity, Grok, or another single-agent surface. Auto-invoke for non-trivial engineering work: build, implement, add, refactor, debug, fix, review, audit, plan, scope, design, brainstorm, ship, or deploy. Trigger with /hyperflow:hyperflow, "use hyperflow", "apply the doctrine", or automatically on any task-shaped message.

FileKindSize
DOCTRINE.mdmarkdown96.9 KB
SKILL.mdskill md9.1 KB
VERSIONother6 B
adaptive-brainstorming.mdmarkdown13.4 KB
artefact-format.mdmarkdown13.7 KB
background-agents.mdmarkdown13.3 KB
brainstorming-advanced.mdmarkdown6.1 KB
consultation.mdmarkdown4.7 KB
design-system.mdmarkdown7.4 KB
doctrine-extensions.mdmarkdown9.2 KB
escalation.mdmarkdown16.8 KB
failure-recovery.mdmarkdown7.6 KB
feature-phases.mdmarkdown7.0 KB
flow-profiles.mdmarkdown20.9 KB
git-workflow.mdmarkdown5.9 KB
latency-patterns.mdmarkdown21.0 KB
memory-system.mdmarkdown15.3 KB
mobile.mdmarkdown4.4 KB
motion.mdmarkdown7.4 KB
output-style.mdmarkdown8.7 KB
personas-A.mdmarkdown36.8 KB
personas-B.mdmarkdown26.0 KB
project-analysis.mdmarkdown8.3 KB
quality-gates.mdmarkdown2.0 KB
review-levels.mdmarkdown4.4 KB
reviewer-prompt-batched.mdmarkdown8.6 KB
reviewer-prompt.mdmarkdown4.4 KB
security.mdmarkdown4.6 KB
session-handoff.mdmarkdown7.4 KB
session-memory.mdmarkdown1.3 KB
task-templates.mdmarkdown2.8 KB
task-tracking.mdmarkdown6.7 KB
task-triage.mdmarkdown17.3 KB
web-research.mdmarkdown4.5 KB
worker-prompt-lean.mdmarkdown5.9 KB
worker-prompt.mdmarkdown17.8 KB

artefact-format.md

View on GitHub
# Artefact Format

How long-form artefacts written under `.hyperflow/` should be structured so the user can open the file in their editor and grasp it in under 10 seconds.

Applies to every planning artefact the orchestrator produces. **All artefacts live under `.hyperflow/`** — never at repo root, never in `docs/`, never in ad-hoc folders. See [DOCTRINE.md](DOCTRINE.md) rule 8 file-first clause for the canonical-location table and banned-location list.

| Artefact | Path | Written by |
|---|---|---|
| Task decomposition (single-phase) | `.hyperflow/tasks/<slug>.md` | `scope` Step 4 |
| Feature (multi-phase) | `.hyperflow/features/<slug>/feature.md` + `phase-<n>-<name>/` folders | `scope` Step 4 — see [feature-phases.md](feature-phases.md) |
| Spec (final) | `.hyperflow/specs/<slug>.md` | `spec` Step 8 |
| Spec (in-progress draft) | `.hyperflow/specs/<slug>.draft.md` | `spec` Step 7 progressive |
| Design system (living) | `.hyperflow/design/system.md` | `design` Step 2 · `designer` agent |
| Audit findings | `.hyperflow/audits/<YYYY-MM-DD-HHmm>-<scope>.md` | `audit` Step 5 |
| Audit-fix spec | `.hyperflow/specs/audit-<YYYY-MM-DD>-<slug>.md` | `audit` Step 6 fix-gate |
| Project memory | `.hyperflow/memory/<category>.md` | `scope` Step 6 · `cache` CRUD |
| Layer-0 analysis | `.hyperflow/profile.md`, `architecture.md`, etc. | `scaffold` |

The `docs/` folder is reserved for polished end-user / contributor documentation (installation guide, provider setup). Never put a working spec or task plan there.

## Core conventions

- **No decorative icons** in any file (`⚡ ✓ ✗ ▸ → • 🚀 📦 ⚠️ 🟢 🔴 *` banned as label prefix per [output-style.md](output-style.md)).
- **Status blocks use markdown tables, not box-drawing characters.** Box-drawing (`╭─╮╰─╯│`) was used in earlier doctrine versions and broke alignment when Writers mis-counted characters (real failure pattern, 2026-05-16). Tables auto-align in every renderer and degrade gracefully in raw text view.
- **Progress bars are text-only:** ``` `████████░░░░░░░░░░░░` ``` wrapped in backticks so the half-blocks render as inline code (8 filled + 12 empty for 8/20). No coloured emoji bars.
- **Section headers** use plain `##` (H2) — never decorated with brackets or hashes for visual weight. The H2 itself is the weight.
- **Tables for any structured list of 3+ items** — file lists, batches, costs, severity counts. Easier to scan than bullet trees.
- **Inline file paths** stay in backticks (`` `path/to/file` ``) and end with a one-line role hint: `` `path/to/file` — what it does ``.
- **Severity / status words** are plain text, never coloured: `low / medium / high`, `pending / in_progress / completed`, `Critical / Important / Suggestion / Praise`.

## The status block (mandatory at top of every artefact)

A markdown table that summarises the artefact's current state. The user reads this first; everything below it is detail. **Use a table, not box-drawing characters** — tables auto-align in every markdown renderer (GitHub, VS Code preview, Obsidian, etc.) and degrade gracefully in raw text. Box-drawing breaks the moment a Writer mis-counts characters (real failure pattern, 2026-05-16).

```markdown
## Status

| Field      | Value                                            |
|------------|--------------------------------------------------|
| Status     | <pending \| in_progress \| approved \| completed> |
| Progress   | `████████░░░░░░░░░░░░`  7 / 15 sub-tasks (47%)   |
| Branch     | `feat/<slug>`                                    |
| Commits    | 7 since main · per-task cadence                  |
| Wall-clock | 12m elapsed · ETA ~8m                            |
| Tokens     | 30 agents · ~365k total                          |
| Specialists| `api-reviewer, security-reviewer · debugger`     |
```

Field rules:

- **Status** — one word from the artefact's lifecycle vocabulary
- **Progress** — only on task files; spec files use `Section 4 / 5 approved` style; audit files omit the row (use Verdict instead — see audit additions below)
- **Branch / Commits** — only on task files (omit rows on spec/audit files)
- **Wall-clock / Tokens** — only when live (omit rows on completed-and-archived files; or replace with totals + `· final`)
- **Specialists** — the Brain-decided responsible specialist agents ([`../../agents/README.md`](../../agents/README.md)) for this artefact; present on spec + task files so `dispatch`/`audit` inherit the roster (omit only when none apply)
- Progress-bar string goes in backticks so the box-drawing characters render as inline code and don't trigger markdown italics on `*` or emphasis on `_`
- Always exactly two columns (Field / Value). Markdown auto-pads to the widest cell — no character counting required

When the artefact is completed and frozen, replace live counter rows (Progress / Wall-clock / Tokens) with their final values and append `· final` to each.

## Visual dependency diagram

When an artefact has 3+ batches or sections with dependencies, include an ASCII flow under `## Execution plan` (task files) or `## Section dependencies` (spec files). Plain Unicode arrows only — no boxes, no colours.

```
Batch 1 — Doc surface alignment        (4 parallel)
  T1 · T2 · T3 · T4
       ↓
Batch 2 — Mirrors + schema             (7 parallel · depends on T1)
  T5 · T6 · T7 · T8 · T9 · T10 · T11
       ↓
Batch 3 — Wire compact subcommand      (1 sequential)
  T13
       ↓
Batch 4 — Final integration review     (1 sequential)
  T15
```

Use `↓` for sequential, ` · ` (space-dot-space) for parallel siblings on one line. Never draw boxes around batches — adds noise without information.

## Per-task / per-section line format

The `<slug>.md` task file is a terse **roster**: each sub-task or section gets one checkbox line + one indented detail line. No multi-paragraph descriptions in the *roster* file — the full implementation detail lives in the per-sub-task **brief file** (below), and design detail in the spec.

```
- [x] T1 — Writer · Author compaction protocol reference
       Read: spec, cache/SKILL.md · Create: skills/cache/references/compaction.md · Complexity: medium · Specialist: searcher · Brief: <slug>/T1.md
- [ ] T2 — Implementer · Add memory.compactionThreshold to config/schema.json
       Modify: config/schema.json · Complexity: low · Specialist: backend-reviewer
```

The detail line is two spaces indented + the file path(s) + complexity + the responsible specialist, and — for non-trivial sub-tasks — a `Brief: <slug>/T<id>.md` pointer to the full brief. **Trivial** sub-tasks (1 file ∧ ~≤10 LOC ∧ obvious — a typo, a single config flag) carry NO brief pointer and get only this terse line; don't over-document a typo.

## Per-sub-task brief file (`.hyperflow/tasks/<slug>/T<id>.md`)

`/hyperflow:plan` authors a full, self-contained implementation brief per **non-trivial** sub-task so the build runs faithfully on a cheaper model (or a second handoff session) — the strong planning model pays the authoring cost once; dispatch transcribes. The brief is the [`worker-prompt.md`](worker-prompt.md) body, written at plan time:

```
## Task          — one verb-led objective
## Why           — 1-3 sentences; what changes for the user/system
## Scope         — IN: what this brief owns · OUT: what siblings own / is deferred
## Files in scope — Read / Modify / Create, each with the EXACT change described (spec-level prose, no code skeletons)
## Acceptance criteria — concrete shape-level PASS checks the Reviewer verifies
## Test cases    — the realistic domain set (no formulaic placeholders) + ≥1 end-to-end / integration scenario
                   (real inputs → real expected outcome; name the tool — Playwright / Maestro / supertest / …),
                   or an explicit `E2E: N/A — <why>`
## Related context — file:line patterns to mirror, related sibling sub-task IDs
## Gotchas       — convention traps, edge cases, irreversible steps
```

Spec-level prose only — describe the change, the implementer writes the code. The brief is the **contract**: the per-batch Reviewer PASS/NEEDS_FIX against its Acceptance criteria + Test cases (including the E2E case). In `feature` mode the same brief content lives in each `phase-<n>-<name>/tasks/T<id>.md`.

## Scope-at-a-glance table

When the artefact touches more than 5 files, include a roll-up table under `## Scope at a glance`. Helps the user see the blast radius without reading every batch.

```
| Surface       | Files | Created | Modified | Risk   |
|---------------|------:|--------:|---------:|--------|
| Docs          |     3 |       0 |        3 | low    |
| Skill bodies  |     7 |       0 |        7 | low    |
| Wiring        |     2 |       0 |        2 | medium |
| Runtime code  |     1 |       0 |        1 | medium |
| **Total**     |**13** |   **0** |   **13** |        |
```

Risk is the *integration* risk of that surface, not difficulty: `low / medium / high`. The Planner sets it from the triage classification.

## Affected-files grouping

Group by lifecycle, not by directory. The user wants to know what gets created vs what gets modified.

```
**Created (N)**
- `path/to/new-file.md` — one-line purpose

**Modified (N)**
- `path/to/existing.md` — one-line change description

**Skipped (confirmed N)**
- `path/to/skipped.md` — why it's not touched (e.g. "does not enumerate subcommands")
```

The `Skipped` section is mandatory when the spec lists files that the Planner consciously decided not to touch — prevents future implementers from re-asking "what about X?"

## Cost table

```
| Role      | Agents | Tokens   |
|-----------|-------:|---------:|
| Reviewer  |     16 |     ~80k |
| Worker    |     14 |    ~140k |
| **Total** | **30** | **~220k**|
```

Always at the bottom under `## Estimated cost`. After completion, replace with `## Actual cost` and the real numbers.

## Spec file additions

Spec files add three extra sections beyond the task-file template:

1. **TL;DR** — first H2 under the status block. 2–3 sentences in plain English. What the feature does + the single most important design decision.
2. **Components** — bullet list of named components (compact subcommand handler, Compaction Writer, etc.) with one-line role. Lets the Planner cross-reference Section 1 names without re-reading the architecture prose.
3. **Trade-offs accepted / rejected** — explicit list at the end of `## 3. Key decisions`. What the design said no to and why. Most useful section for future implementers and audit reviewers.

When the [`architect`](../../agents/architect.md) agent authored the design (architect-typed / high-complexity / multi-subsystem work), `## 1. Architecture` embeds a Mermaid component/container graph and `## 2. Data flow` embeds a Mermaid data-flow diagram — the diagram precedes the implementation. These are fenced ` ```mermaid ` blocks (not the plain-Unicode dependency diagram above, which stays ASCII); the Step 8 final-spec Reviewer checks both graphs are present.

## Audit file additions

Audit files replace the status table with a verdict table (no Progress / Branch / Commits / Wall-clock / Tokens rows since audits aren't long-running tasks):

```markdown
## Status

| Field    | Value                                              |
|----------|----------------------------------------------------|
| Verdict  | `NEEDS_FIX`                                        |
| Scope    | `main..HEAD` (13 files · 284 insertions)           |
| Level    | L3                                                 |
| Findings | 0 Critical · 4 Important · 4 Suggestions · 5 Praise |
| Date     | 2026-05-16 17:30                                   |
```

Then findings are grouped by severity in this order: **Critical → Important → Suggestion → Praise**. Each finding:

```
### [Important] config/features.json:128 — cache.purpose omits `compact`

**Issue:** The `skills[].purpose` field for the cache skill still reads "Show, search, add, edit, prune, archive, clear, stats, migrate" — `compact` is missing.

**Fix:** Append `, off, compact` to the `purpose` string.

**Why it matters:** README and capabilities array both mention compact; this field is the third source of truth and drives the marketplace listing.
```

Three short blocks per finding (Issue / Fix / Why it matters). Each block is one short paragraph max — if a finding needs more, it's a design question, not an audit finding, and belongs in a spec.

## Chat output (the index, not the content)

The orchestrator's chat output during artefact creation should be the *index pointing at the file*, not the content. Keep these conventions:

- **One short status box** when the artefact is written (or finalized). Includes: file path, line count, lifecycle phase.
- **No file content** echoed into chat. Even for review summaries — the file is the source of truth.
- **Hand-off lines** are one sentence followed by the build-location gate: `Plan ready — .hyperflow/tasks/<slug>.md (5 batches · 15 sub-tasks). Where should this be built?`
- **Gate prompts** reference the file: `Design draft ready at .hyperflow/specs/<slug>.draft.md — review the file, then approve or revise.`

Chat scrolls; files persist. Long-form goes to files.

## When NOT to use this format

Two cases where the format relaxes:

1. **`fast` profile, single-sub-task chains.** A one-task, one-batch run is overkill for the full template. The minimum task file is: H1 title, Goal one-liner, single batch with one `[ ]` line, Status block. Skip Scope-at-a-glance, dependency diagram, cost table.
2. **Audit-fix specs derived from existing audit files.** Don't duplicate the Findings section — link back to the audit file in a `> Source: .hyperflow/audits/<file>.md` blockquote at top.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 196kUpdated Claude CodeCodexVerifiedInstall