adding-a-feature
/adding-a-feature
The end-to-end checklist for adding or changing a feature in this repository (most often a new commentable-html behavior, but also a site behavior or a new tool). Use whenever you are about to implement, ship, or review a feature or user-visible behavior change here, so it lands complete on the first pass instead of rediscovering the gates one CI failure at a time. Trigger on: add a feature, new feature, implement a behavior, new commentable-html behavior, change behavior, ship a feature, feature PR, spec row, feature-id, TDD red-first, covering test, version bump, changelog, rebuild artifacts
- Author
- urikanonov ↗
- Repository
- ai-marketplace ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
The end-to-end checklist for adding or changing a feature in this repository (most often a new commentable-html behavior, but also a site behavior or a new tool). Use whenever you are about to implement, ship, or review a feature or user-visible behavior change here, so it lands complete on the first pass instead of rediscovering the gates one CI failure at a time. Trigger on: add a feature, new feature, implement a behavior, new commentable-html behavior, change behavior, ship a feature, feature PR, spec row, feature-id, TDD red-first, covering test, version bump, changelog, rebuild artifacts
Original author description
The end-to-end checklist for adding or changing a feature in this repository (most often a new commentable-html behavior, but also a site behavior or a new tool). Use whenever you are about to implement, ship, or review a feature or user-visible behavior change here, so it lands complete on the first pass instead of rediscovering the gates one CI failure at a time. Trigger on: add a feature, new feature, implement a behavior, new commentable-html behavior, change behavior, ship a feature, feature PR, spec row, feature-id, TDD red-first, covering test, version bump, changelog, rebuild artifacts
How it works
- 0. Before any code: track it and branch it
- 1. Write the test first (TDD, genuinely red)
- 2. Give the behavior a spec row
- 3. Implement in the owning split partial (never a monolith)
- 4. Document it with a minimal SKILL.md footprint
- 5. Register the new files with the coverage gates
- 6. Add or extend a demo, then run the E2E audit on it
- 7. Version, changelog, and rebuild every artifact
- 8. Validate, run the suites, and open the PR
- Checklist
SKILL.md preview
---
name: adding-a-feature
description: >-
The end-to-end checklist for adding or changing a feature in this repository (most often a new
commentable-html behavior, but also a site behavior or a new tool). Use whenever you are about to
implement, ship, or review a feature or user-visible behavior change here, so it lands complete on
the first pass instead of rediscovering the gates one CI failure at a time. Trigger on: add a
feature, new feature, implement a behavior, new commentable-html behavior, change behavior, ship a
feature, feature PR, spec row, feature-id, TDD red-first, covering test, version bump, changelog,
rebuild artifacts, split partial, MODULES.md, coverage gate, add a demo, E2E audit, SKILL.md
footprint, scaffold and apply tool.
---
# Adding a feature
The end-to-end workflow for adding a new feature to a plugin in this repository (most often a new
`commentable-html` behavior). It is the single checklist to follow so a feature ships complete on the
first pass instead of rediscovering the gates one CI failure at a time. It complements
[AGENTS.md](../../../AGENTS.md) (authoritative where they overlap) and
[testing-guidelines.md](../../../docs/testing-guidelines.md) (authoritative for tests).
The worked example throughout is the editable notes field (`data-cmh-note`): an authored element that a
reviewer types into, whose edit is tracked, handed back through Copy all, and cemented into the source
with a tool. It touched every surface below, so it is a good template.
## 0. Before any code: track it and branch it
1. **Issue first (non-negotiable).** Search existing issues (`gh issue list --search "<topic>"`, add
`--state all` for closed history), then create or reuse a `task`-labeled GitHub Issue, set it
`In Progress`, and assign it to yourself. Prefer the in-repo `task` skill, which wraps the
`gh` calls. Capture any follow-up you discover as its own issue the moment it comes up.
2. **Fresh worktree off the latest `origin/main`.** `git fetch origin`, then
`git worktree add -b <branch> .worktrees/<name> origin/main` (or `python scripts/task.py start <n>`,
which also claims the issue and starts the branch stamp). Never edit the primary tree in place.
Enable the hooks once per worktree: `git config core.hooksPath .githooks`.
3. **Plan and get approval.** For a user-facing change, write the plan (a commentable-HTML plan by
default), review it, and get a go-ahead before writing code.
## 1. Write the test first (TDD, genuinely red)
Every feature ships with a covering automated test in the same PR, and the test is written first and
confirmed RED against the current code. Read [testing-guidelines.md](../../../docs/testing-guidelines.md)
before you start; the traps it documents (pinning the change to a marker only the change introduces,
rebuilding generated output before asserting, hermetic Playwright specs, choosing an observable viewport)
are the ones most often relearned the hard way.
- Runtime behavior goes in a Playwright spec under `plugins/<plugin>/dev/tests/NN-topic.spec.js`; author
tooling goes in a Python `unittest`/`pytest` module beside it.
- Use inputs that cannot pass by accident. The notes tests use a normalization-hostile value (leading and
trailing spaces, an internal double space, an entity, a newline) so a shallow implementation is caught.
- Playwright specs load the BUILT `dist`, so run the build (step 3) before asserting a runtime change, or
the spec measures stale code.
## 2. Give the behavior a spec row
Add an `AREA-NN` row to the owning spec (`plugins/<plugin>/dev/SPEC.md`, or `site/tests/SPEC.md` for the
site) for every behavior, and name the exact covering test in the row. Reuse an id when you refine a
behavior; never renumber or delete a shipped id. A behavior the spec does not tie to a passing test is
not done. The notes feature added `CMH-NOTE-01..15` plus a `CMH-DEMO-05` row for its demo.
## 3. Implement in the owning split partial (never a monolith)
The `commentable-html` runtime and CSS live only as numbered partials under
`dev/assets/js/NN-topic.js` and `dev/assets/css/NN-topic.css`; `build.py` concatenates each directory by
sort order, so adding a behavior is usually adding one partial (the notes runtime is
`37-notes.js` + `86-notes.css`). Never recombine them into a `commentable-html.js`/`.css` monolith - a
test forbids it.
Wire the behavior into the shared layers it needs (the notes feature touched all of these; a smaller
feature touches fewer):
- **Sidebar** (`50-sidebar.js`): a change card and a click-handler branch, merged into the
position-sorted card list and the empty-state guard.
- **Search** (`51-comment-search.js`): if the card should be findable.
- **Copy all** (`56-copy-clear.js`): a bundle section, a machine-readable JSON line, and the "has changes"
gate (`_copyAllState`).
- **Clear** (`62-sortable-tables.js`): whether the global Clear should reset the new state.
- **Badge** (`70-mode-badge.js`): a Not-shareable reason while the state is unsaved.
- **Exports** (`65/66/67/68`): a bake so the exported source carries the state.
- **Startup** (`95-startup.js`): the init call (mind ORDERING - anything that adds `cm-skip` and removes
its text from the offset system must run before offset restoration, like the diff and notes layers do)
and the open-sidebar-on-load gate.
For round-trippable state, follow the scaffold + apply pair: a `tools/<topic>/<topic>_scaffold.py` that
emits the markup and a `tools/<topic>/<topic>_apply.py` that deterministically and idempotently cements a
Copy-all payload back into the source. Add authoring guardrails to `tools/validate/checks/<topic>.py` and
wire them into `validate.py`.
## 4. Document it with a minimal SKILL.md footprint
Put the detail in an on-demand `references/<topic>-contract.md` and add only a short linked line to
`SKILL.md` (and a scaffold-tool mention). The link is a gated invariant: every `references/*.md` must be
reachable from `SKILL.md` or `references/file-inventory.md`, so an unlinked reference fails CI. Update the
`tools/` bucket enumeration in `references/file-inventory.md` when you add a bucket.
## 5. Register the new files with the coverage gates
Adding a partial or a tool trips a coverage gate unless you also update its map:
- A new `dev/assets/js/` or `dev/assets/css/` partial needs a row in that directory's `MODULES.md`, and
every SPEC area it claims must be a real, test-backed `AREA-NN` row.
- A new shipped tool needs its entry in `dev/tests/test_tools_layout.py`'s `EXPECTED` map.
## 6. Add or extend a demo, then run the E2E audit on it
Ship the feature in a live demo so a user can try it:
- Add `dev/examples/src/report-<name>.html` (a full standalone doc with a unique `data-comment-key`) and a
companion `examples/prompt-<name>.md`, or extend an existing demo. `build.py` auto-discovers
`report-*.html`; a report with no `dev/examples/src/` source, or with no companion prompt, fails CI.
- Add a `CMH-DEMO-NN` spec row and a test that names it.
- Run the E2E Playwright audit against the demo (`npx playwright test <spec>`) to confirm every
interaction works before shipping. The notes feature ships `report-notes.html` and its end-to-end
round-trip test exercises the demo path.
## 7. Version, changelog, and rebuild every artifact
- Bump `dev/VERSION` (a shipped-source change requires a bump; pick a distinct version lane up front when
PRs are in flight) and add a matching `## [x.y.z]` heading to the plugin's `CHANGELOG.md`.
- Regenerate everything in one command: `python scripts/rebuild_all.py` (the layer dist, the
version-stamped Playwright fixtures, and the site). Never hand-edit a generated artifact - each carries a
`DO NOT EDIT` banner and a `--check` gate.
## 8. Validate, run the suites, and open the PR
```bash
python scripts/validate_marketplace.py
python scripts/validate_markdown.py
python scripts/rebuild_all.py --check # every generated artifact is in sync
```
Run the Python suite (`python -m pytest` from `plugins/<plugin>/dev/tests`) and the relevant Playwright
spec (`npx playwright test <spec>`). The full browser suite is occasionally flaky under high parallelism -
re-run any failure in isolation before treating it as real; CI is the authoritative Playwright gate. The
pre-push hook mirrors the required checks (validators, changelog sync, version bump, and the `--check`
drift guards), so a push that would fail a required check is caught locally first. Do NOT put the version
in the PR title; describe the change.
Push in BATCHES once the PR is open, not per fix. Every push to an open PR re-runs the required
checks, and nearly all of them cancel the run in progress - only `require-owner-approval` and
`All conversations resolved` deliberately do not - so a second push moments later mostly just
restarts the first. Finish the local verification above, fold in every outstanding review comment,
and then push once - see the "BATCH YOUR PUSHES TO AN OPEN PR" bullet under "Branch and PR rules" in
[AGENTS.md](../../../AGENTS.md). Before the PR exists, push freely: a feature-branch push runs no
required check, and it keeps the work recoverable if the session is interrupted. Fewer rounds means
pushing fewer times, never skipping or weakening a check.
Before you finish a feature PR, run two rounds of the `multi-duck` review and stamp the PR body
(`Multi-Duck passed`, or an opted-out box with a reason) - the required `multi-duck-review` check fails an
unstamped feature PR.
## Checklist
- [ ] `task`-labeled issue `In Progress` and assigned, fresh worktree off `origin/main`, hooks enabled.
- [ ] Failing test written first and confirmed red; `AREA-NN` spec row names it.
- [ ] Behavior implemented in the owning split partial (no monolith) and wired into every shared layer it
needs.
- [ ] Scaffold + apply tools and a validator guardrail for round-trippable state.
- [ ] `references/<topic>-contract.md` added and linked; minimal `SKILL.md` line; `file-inventory.md`
bucket updated.
- [ ] `MODULES.md` row(s) and `test_tools_layout.py` map updated.
- [ ] Demo added or extended, with a companion prompt, a `CMH-DEMO` row, and the E2E audit run against it.
- [ ] `dev/VERSION` bumped, `CHANGELOG.md` updated, `rebuild_all.py` run.
- [ ] Validators, `rebuild_all --check`, the Python suite, and the touched Playwright spec all pass.
- [ ] Two rounds of `multi-duck` run and the PR body stamped.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · urikanonov/ai-marketplace | 100 | MIT |
| builderio/agent-native | 100 | MIT |
Database snapshot: 13.11.2026 · package version 94ab71b7520a (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90dev-feature
Use when adding or changing behavior: a new feature, a behavior change, or a user-visible improvement. - 100workflow-build-feature
Build a feature end to end: spec and TDD, implement, unit tests, Playwright check, PR. Use when "build a feature" or "implement this end-to-end". Spec/TDD loop only → workflow-spec-tdd. One bug → workflow-fix-and-ship. - 100acp-feature-add
Use when the user asks to add a new feature, add a new API/endpoint/page/component, implement a new capability, or extend existing functionality with new behavior. Forces a plan-before-code loop, scoping non-goals, and verifying the new behavior end-to-end. - 100tdd
Test-first implementation discipline. Use when adding a function or feature, fixing a bug, changing existing behavior, or when implementation code already exists with no test covering it. - 100add-a-feature
Decide whether work needs a feature flag (any change to product behavior users can see does), then declare it, roll it out (per organization, for everyone, cloud or self-hosted), revert or kill it. Use for any user-visible behavior change, and when finishing or removing a rollout. - 100tdd-feature
Red-green-refactor scaffold for building new features with TDD. Write failing tests first, then implement to pass. Use when building new features test-first.