webjs-file-issue

File a new issue on the webjs project board

The webjsdev/webjs project tracks new work through GitHub issues added to the project board at https://github.com/orgs/webjsdev/projects/1. This skill captures a fresh task as an issue, files it, and adds it to the board so it appears in the Todo column.

Inputs

The user describes the task in natural language. Extract:

• A short, imperative-mood title (under 70 chars; the same shape as a good commit subject).
• A dogfood: title prefix when the task came from dogfooding, meaning it surfaced while actually building a real app with webjs and hitting a framework gap, an idiomatic-code divergence, or a rough edge (the way #353 and #356 were found). Prefix the title dogfood: so the board shows at a glance which issues came from real app-building versus planned framework work. A task that did not come from building an app (a planned feature, a refactor, an internal bug) takes no such prefix. If it is unclear whether the task is dogfood-originated, ask, or look at whether the user was driving a generated/example app when the issue came up.
• A body that follows the issue-body convention used in #112 / #113 / #114: short problem statement, design rationale or context, acceptance-criteria checklist, AND an implementation-notes section (see "Issue body convention" below for why this is mandatory).
• A label if the type is clear from the description: enhancement for new features and improvements, bug for something broken, documentation for docs work. If unclear, default to enhancement (the most common case on this project).

If the user's description is very thin (e.g. "track adding dark mode as a todo"), ask one clarifying question before filing: "Want me to scope this out a bit, or file the placeholder with just the title and you'll fill in details on the issue later?" Either answer is fine; just confirm before creating.

Steps

1. Create the issue AND assign it to vivek7405. Every webjs issue is assigned to the owner (vivek7405) at creation so the project board shows ownership at a glance.

   gh issue create --repo webjsdev/webjs \
     --title "<title>" \
     --body "<body>" \
     --label <label> \
     --assignee vivek7405
   

   Capture the returned issue URL and number.

2. Add it to the project board.

   gh project item-add 1 --owner webjsdev --url <issue-url>
   

   The card lands in Todo by default. No need to set Status explicitly.

3. Report back briefly. One short message: issue number + title + a link, and confirm it's on the board in Todo. Do not invent next steps; just confirm the artefact exists.

Issue body convention

Standing assumption: every issue here is implemented by an AI agent working COLD. The agent that picks the issue up has ZERO access to the conversation that produced it. So the body is the entire brief, and it MUST carry enough for that agent to implement correctly without re-discovering everything: not just WHAT and WHY, but WHERE (the concrete files / functions / dirs to edit), the LANDMINES (known gotchas, prior incidents, non-obvious constraints), and the INVARIANTS to respect. An issue that reads well to a human who was in the room but leaves an agent guessing the file paths is under-specified. The user should not have to ask for this each time; it is the default.

Before filing a scoped issue, do LIGHT codebase grounding so the body cites real landmarks, not vague pointers: grep for the relevant files / functions, name them with their paths (and approximate line or symbol when helpful), and capture any gotcha you hit or know about. A few grep / Read calls now save the implementing agent a cold-start investigation later.

Match the shape of issues #112 / #113 / #114 (all visible on the board):

## Problem

<one or two paragraphs describing what's wrong or what needs adding>

## Design / approach

<the proposed direction, alternatives considered if any, references to prior art>

## Implementation notes (for the implementing agent)

<the WHERE and the LANDMINES, grounded in the actual codebase:>
- Where to edit: the concrete file(s) / function(s) / dir(s), with paths (e.g. `packages/cli/lib/create.js` `scaffoldApp()` around L275). Name the entry points, not just the area.
- Landmines / gotchas: known traps, a prior incident this touches (link the issue/PR), runtime or build constraints, anything non-obvious that will bite an agent who does not know it.
- Invariants to respect: project rules the change must not break (link AGENTS.md items where relevant).
- Tests + docs surfaces the change must touch (which test layer, which markdown / docs-site pages).

## Acceptance criteria

- [ ] <observable result 1>
- [ ] <observable result 2>
- [ ] A counterfactual proves the test actually fires (where applicable)
- [ ] Tests cover the new behaviour, at every layer it touches
- [ ] Docs / AGENTS.md updated if the public surface changed

The Implementation notes section is mandatory for any scoped issue, precisely because the implementer is an agent with no conversational context. If you cannot fill it in without investigating, do the light grounding first (above), then file.

For a thin placeholder (user just wants the line item tracked, explicitly deferring the detail), skip the Design / Implementation-notes / Acceptance sections; leave a single short paragraph in Problem and mark the issue "needs scoping". Use this ONLY when the user opts into a bare placeholder; the default for a real task is the fully-grounded body above.

What this skill does NOT do

• Does not start a branch or open a PR. Those happen via webjs-start-work once the user is ready to work the item.
• Does not move the card out of Todo. Status changes happen via webjs-start-work (Todo to In progress) and the Closes #N automation (In progress to Done on merge).
• Does not consult or update internal task trackers or memory.

Failure handling

• If gh issue create fails (auth, label missing, network): surface the error and offer to retry with adjusted args.
• If gh project item-add fails after the issue was created: report the partial state ("issue #N created but not on board yet") and offer to add it manually.
• If the user's description seems to duplicate an existing open issue: search the board first with gh project item-list 1 --owner webjsdev --format json and ask whether to file anyway or use the existing one.