a-novel-kit
OrganizationDevelopment tools backing a-novel and a-novel-kit. Home of the a-novel CLI and AI skills.
Categories
Indexed Skills (27)
attribute-ai-commits
Add GitHub-linked AI co-authors to Git commit trailers without inventing provider identities. Use whenever an AI agent that created or materially changed committed content writes, amends, or reviews a commit message. Trust the repository registry for known agents and defer missing-agent discovery to the register-ai-agent skill.
choose-dependency
Decide whether a need is met by the standard library, an existing dependency, a new third-party library, or an internal implementation — and which package to pick when importing. Use it whenever a change adds a library, weighs build-vs-buy, swaps an internal helper for a dependency (or back), or picks between competing packages. Feeds plan-feature's build-vs-buy section.
coordinate-landing
Vocabulary, invariants, and operator runbook for the cross-repo **landing saga**: how a multi-repo Epic lands atomically, recovers from a partial landing, rolls back, and releases through the `a-novel-kit/workflows` actions (merge-gate, epic-freeze, epic-rollback, release-train, the AGENT_KILL_SWITCH halt). Load it when a change spans several repos under one Epic. It owns the saga vocabulary and the **Epic Atomicity Rule**, and defers version mechanics to `manage-versions`, per-repo release mechanics to `prepare-release`.
document-code
Write and improve code documentation. Use whenever asked to document code, add comments, write a doc comment, annotate a function, document a package, explain a file's purpose, or clean up unclear or outdated comments — however phrased ("doc this"). Applies to Go, Bash/shell, YAML, Svelte, SQL, TypeScript, and other source or config files. Invoke before writing any documentation, even for one function.
git-conventions
Git workspace hygiene (clean-tree pre-flight, pruning a scratch stack), branch naming, commit message format, and workflow conventions for Agora backend services. Use it whenever starting or finishing work in a checkout, creating a branch, writing a commit message, or grouping changes. Referenced by implement-feature and any other skill that touches git. Pair with attribute-ai-commits whenever an AI agent materially contributed to a commit.
implement-feature
Implement a change to an a-novel backend SERVICE repo using a layered branch strategy. Use whenever implementing a new API endpoint, schema change, business logic, or client update. Covers branch decomposition, per-branch testing, and backtracking. Run plan-feature first for non-trivial, multi-repo, or architectural work. Backend services only — not platform (frontend) repos.
manage-versions
Cross-repo version management for a-novel / a-novel-kit. Load it whenever a change spans repos that must stay version-compatible to merge — an unreleased `golib` or `pkg/go` dependency, a proto or REST contract change, a breaking change to a published symbol. Covers git-tag semver, exact `go.mod` pins, commit-SHA pseudo-versions, the dependency-releases-FIRST merge order (the consumer re-pins to the released tag), and staged rollouts. Pairs with `git-conventions`, `implement-feature`, `open-pull-request`, `write-*`.
monitor-ci
Monitor GitHub Actions CI runs on a pushed branch or open PR, classify failures, and fix them where safe. Use whenever waiting on CI, investigating a failing check, judging a failure real or flaky, or iterating a branch to green. Covers the Agora CI job map and the retry/fix loop. Pairs with open-pull-request (the post-push handoff) and git-conventions.
open-pull-request
Push a branch and open a GitHub pull request for Agora backend services. Use whenever shipping work — features, fixes, refactors, chores. Covers pre-flight checks, base branch, PR title and body, draft mode, and updating an existing PR instead of re-creating it. Pairs with git-conventions (commit/branch format) and monitor-ci (post-push CI).
plan-feature
The planning and technical-design gate before any non-trivial implementation in the a-novel / a-novel-kit workspace. Use it when a change spans multiple repos, touches an architecture or data model, introduces a service, platform or library, weighs build-vs-buy, or is ambiguous about what to build. It captures the agreed design as a GitHub planning **issue** (Initiative / Epic / Task sub-issues), then hands off to implement-feature. Skip trivial single-repo edits.
prepare-release
Run BEFORE cutting a release: it reads the commits since the last tag, proposes the version bump (`fix`/`chore`→patch, `feat` or an absorbable breaking change→minor; a major is never derived from commits — it is a planned `vX`-line initiative), and drafts the per-version migration guide (`docs/migrations/vX.Y.Z.md`) when consumers must act. Use it when asked "is this patch / minor / major?", "what changed since the last release?", or "does this need a migration guide?". ADVISORY — the human cuts the release; this never tags, pushes, or publishes.
register-ai-agent
Discover, programmatically verify, and register a GitHub-linked AI co-author identity. Use only when attribute-ai-commits reports status missing for the current agent, or when explicitly asked to add a new agent to the repository co-author registry. Publish the registry change through a pull request.
resolve-pr-feedback
Survey a pull request's state (CI, review threads, reviewer status) and work through reviewer feedback on any repo in the a-novel / a-novel-kit orgs. Use it when checking on an open PR, reading Copilot or human review comments, replying on or resolving a thread, re-requesting review, or answering comments under an issue. Pairs with plan-feature, which owns the issue body.
triage-issues
Manual triage and board-grooming pass over open GitHub issues in the a-novel / a-novel-kit orgs. Use it when asked to "run triage", "groom the backlog", "prioritise the issues", or prep a planning meeting. It surveys both org "Tasks" boards, drains the `Triage` queue, sets Priority, Size, due dates and Status, and refines Backlog drafts. Trigger it MANUALLY. Pairs with plan-feature, which creates the issues.
use-a-novel-cli
Canonical reference for the `a-novel` CLI. ALWAYS load alongside any skill that runs tests, builds artifacts, releases, or starts/stops local services. Covers the groups `test`, `build`, `publish`, `repo` (repository config, rulesets, required checks), `run` (daemon-backed `start`/`kill`/`logs`/`env`/`volume`/`ui`) and `core` (daemon lifecycle). Prefer `a-novel <verb>` over raw commands; lint/format/generate live in pnpm scripts (`pnpm lint:go`, `pnpm format:go`), never in Makefiles — deleted from every repo.
write-bash-scripts
Write, review, and maintain Bash shell scripts for Agora backend services. Use whenever creating or editing any .sh file — test runners, build or publish scripts, entrypoints, env setup. Covers error handling, cleanup traps, argument validation, service readiness waits, and portability.
write-dockerfiles
Write, review, and maintain Dockerfiles and compose files for Agora backend services. Use whenever creating or editing anything in builds/ — Dockerfiles, podman-compose files, database init scripts, entrypoint scripts. Covers Go service, job, database, and standalone dev images, and the compose files wiring them together.
write-github-actions
Write and maintain GitHub Actions workflows, composite actions (action.yaml), and repo CI config across the a-novel / a-novel-kit orgs. Use whenever adding or editing a workflow, a shared action in a-novel-kit/workflows, a CI job, a required check, or a ruleset.
write-go-kit
Go conventions for the a-novel-kit shared-library repos under `kit/` (`golib`, `jwt`, …) — the golib-stays-minimal bar, the stricter kit dependency policy, graduating a sub-package into its own community package, and kit test conventions. Load it to write or review Go there, or to decide whether something belongs in `golib` at all. ALWAYS load `write-go` alongside it; a-novel services use `write-go-service`. Pairs with `write-go-tests`, `document-code`, `manage-versions`. Not JS/TS, `kit/nodelib`, or `kit/workflows`.
write-go-service
Clean-architecture conventions for the a-novel backend SERVICES — `app/service-*`, `app/platform-*`, and any repo with the `cmd`/`internal/{config,lib,dao,core,handlers,models}`/`pkg` layout. Load it for Go work there: endpoints, schema changes, business logic, new layers, REST/gRPC handlers, DAO tests. Covers the layer split and import direction, the interface+implementation pattern, transaction scoping, OpenTelemetry, and the service security model. Load `write-go` alongside; `write-go-kit` is the a-novel-kit library counterpart.
write-go-tests
Test conventions for ALL Go code in the a-novel and a-novel-kit organizations — file/function naming, table-driven structure, mockery, assertions, parallelism, cross-package fixtures, helpers, coverage. Load it whenever writing or modifying a Go test file in a backend service OR a shared library. Pairs with `write-go`; layer-specific patterns live in `write-go-service`. Does NOT apply to JS/TS tests.
write-go
Base Go conventions for EVERY Go repo in the a-novel and a-novel-kit orgs — naming, error handling, dependency policy, context, the format/lint discipline, time, and secrets. Load it for ANY Go work in either org, alongside the matching repo-kind skill: `write-go-service` (a-novel services) or `write-go-kit` (a-novel-kit libraries — `golib`, `jwt`). Pairs with `write-go-tests` and `document-code`. Not JS/TS, SQL (`write-sql`), Protobuf (`write-proto`), Dockerfiles (`write-dockerfiles`), or shell scripts (`write-bash-scripts`).
write-js-package
Write, review, and maintain any Agora service's JavaScript/TypeScript REST client package. Use whenever creating or editing files under pkg/js/ — the published client library (pkg/js/rest/), its integration tests (pkg/js/test/rest/), or the package and build config. Covers API methods, type definitions, exports, and test cases.
write-openapi
Write, review, and maintain the OpenAPI 3.1 specification for Agora backend services. Use whenever editing openapi.yaml — adding endpoints, parameters, schemas, responses, or updating descriptions and examples. Covers the REST public API only; gRPC contracts belong to the write-proto skill.
write-project-docs
Write and maintain root-level project docs — README.md, SECURITY.md, CONTRIBUTING.md — for any a-novel / a-novel-kit repo (services, golib, nodelib, workflows, stack CLI). Use it when scaffolding a new project's docs or updating one: new env var, badge, client or Docker section, security contact. Not CODE_OF_CONDUCT.md or in-source comments (document-code).
write-proto
Write, review, and modify Protobuf definitions for Agora backend services. Use whenever creating or editing .proto files — new RPCs, messages, shared types, enums, or breaking-change assessment. Covers internal/models/proto/ and the buf toolchain.
write-sql
Write, review, and maintain PostgreSQL SQL for Agora backend services. Use whenever creating or editing SQL — DAO query files (internal/dao/*.sql), schema migrations (internal/models/migrations/*.sql), or raw SQL embedded in Go: SELECT/INSERT/UPDATE/DELETE queries, DDL (tables, views, indexes, constraints), materialized views, pg_cron jobs.
Bio shown is the top-scored skill's repo description as a fallback — real GitHub bios land in a future update.