RonanCodes/skills/dev-needs-panel

Dev Needs Panel

The outbound sibling of completion-report. Completion-report answers "what did I do". This answers "what do I need from you before I can keep going". One self-contained HTML file per project / worktree, opened when the user is back at the keyboard, with fillable fields and a Save that the agent reads back next session.

This exists because the expensive blocker in an autonomous run is a missing secret or an account the agent can't create. Telling the user about it in a chat transcript they have already scrolled past loses it. A single browsable panel that survives the session, names the exact env vars / accounts / config, and lets the user paste values into it turns a dead run into a queued one.

When to use it

• At the tail of a /ro:night-shift, /ro:ralph, or /ro:planner-worker run that stalled on something only the human can provide (a Stripe key, a confirmed account, a config value).
• On demand when the user asks "what do you need from me" / "what's blocking you".
• As the inbound half of the notify pattern: completion-report shows what shipped, this panel collects what's needed, and the Pushover / Telegram ping can deep-link to it (--url file://...).

Skip it when there are no outstanding needs. An empty panel is noise.

How it works

1. The agent assembles a needs spec (JSON) for the current project / worktree: project name, worktree path, branch, links (repo, PR, dashboard), and a list of needs.
2. scripts/generate.sh renders that spec into one self-contained .html file. No CDN, no external assets - all CSS and JS are inlined.
3. The user opens the file, fills the fields, clicks Save.
4. Save writes a sibling answers file (<panel>.answers.json) next to the panel. The agent reads that file next session to pick up the values.
5. If the browser blocks file writes (the default for a plain file:// open without the File System Access API), Save downloads the JSON and shows the exact path to drop it. Fallback to that: the user just tells the agent "updated" and the agent reads whatever the user pasted in.

Generating a panel

Pipe the spec on stdin, or pass --spec <file>:

bash ~/Dev/ronan-skills/skills/dev-needs-panel/scripts/generate.sh \
  --out .dev-needs/needs.html <<'SPEC'
{
  "project": "makely",
  "worktree": "/tmp/ns-wt/makely-2",
  "branch": "feat/checkout",
  "links": [
    {"label": "Repo", "url": "https://github.com/RonanCodes/makely"},
    {"label": "PR #12", "url": "https://github.com/RonanCodes/makely/pull/12"}
  ],
  "needs": [
    {
      "key": "STRIPE_SECRET_KEY",
      "label": "Stripe secret key",
      "kind": "env",
      "why": "Checkout flow can't be wired without it.",
      "where": "~/.claude/.env",
      "secret": true,
      "required": true
    },
    {
      "key": "stripe_account",
      "label": "Stripe account confirmed",
      "kind": "account",
      "why": "Need a test account to create products.",
      "type": "checkbox"
    }
  ]
}
SPEC

The script prints the absolute path of the written HTML on its last line. With no --out it writes to .dev-needs/<timestamp>-<project>.html in the current repo.

Open it with --open (calls open on macOS), or just hand the user the path / deep-link it from the end-of-run ping.

Needs spec schema

Top-level object:

| Field | Required | Meaning | |------------|----------|---------| | project | yes | Project name, shown in the header and used for the filename slug. | | worktree | no | Worktree path, so it's unambiguous which checkout this is for. | | branch | no | Branch name, shown in the header. | | links | no | Array of {label, url} - repo, PR, dashboard. Rendered as link buttons. | | needs | yes | Array of need objects (below). An empty array renders an empty-state panel. |

Each need object:

| Field | Required | Default | Meaning | |------------|----------|---------|---------| | key | yes | - | Stable identifier the agent reads back from the answers file. | | label | no | key | Human label on the field. | | kind | no | other | env | account | config | other. Shown as a colour tag. | | why | no | - | One line on why the agent is blocked on it. | | where | no | - | Where the value should live (e.g. ~/.claude/.env). | | secret | no | false | Render as a password field. | | required | no | false | Mark the field required (badge + HTML required). | | type | no | text | text | textarea | checkbox. |

Answers file schema

Save writes (or downloads) a JSON sibling of the HTML, named <panel-basename>.answers.json:

{
  "meta": {
    "project": "makely",
    "worktree": "/tmp/ns-wt/makely-2",
    "branch": "feat/checkout",
    "answersFile": "20260628-145541-makely.answers.json",
    "answersPath": "/abs/path/.dev-needs/20260628-145541-makely.answers.json",
    "generatedAt": "20260628-145541"
  },
  "answers": {
    "STRIPE_SECRET_KEY": "sk_test_...",
    "stripe_account": true
  },
  "savedAt": "2026-06-28T13:00:00.000Z"
}

answers is keyed by each need's key. Checkboxes are booleans; everything else is a string.

Reading the answers next session

Next session, before re-running the blocked work:

1. Glob .dev-needs/*.answers.json in the repo, newest first.
2. Read the answers object. Apply each value where its need's where said it should go (e.g. append KEY=value to ~/.claude/.env, never commit secrets).
3. If no answers file exists but the user said "updated", re-read the source of truth the value should live in (e.g. ~/.claude/.env) and proceed.
4. Once consumed, the run can continue from where it stalled.

Gitignore

The .dev-needs/ directory is per-run, machine-local, and may contain secrets the user pasted. It must be gitignored. Add this to the target repo's .gitignore if missing:

.dev-needs/

Never commit a panel or an answers file.

Relationship to other skills

• completion-report is the outbound "what changed" report. This is the inbound "what I need". They pair: a run can end with both, and the ping deep-links to whichever matters.
• telegram / pushover carry the ping. Pass --url file://<panel-path> so tapping the phone notification opens the panel.
• Read skills/completion-report/SKILL.md and skills/telegram/SKILL.md for the shared style; do not edit them.