pikkujs/pikku-feature

Pikku Create-a-Feature

Agent Operating Procedure

Use this skill as an execution checklist, not reference material.

1. Discover before editing. Prefer OpenCode tools such as pikku-meta when available; otherwise run the relevant pikku meta ... --json command and inspect only the focused output you need.
2. Identify the source files that own the behavior. Do not start by reading generated output, .pikku, node_modules, vendored packages, or broad build artifacts.
3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
4. Validate with the narrowest relevant command first, then run pikku-verify or pikku all when functions, wirings, schemas, or generated clients may have changed.
5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.

End-to-end flow: discover → state intent → branch → implement → verify → commit → hand to reviewer.

There is no plan JSON. The branch + diff IS the contract. The reviewer sees real, compiled, working code. Apply = merge. Reject = git branch -D.

Stage 1 — Discover

Run once at the start of every feature request:

yarn pikku meta context --json

This single call returns functions, wires, middleware, permissions, workflows, capabilities (which wire types are in use), and layout (where new files should land).

Only fall back to targeted commands when you need full input/output JSON schemas (yarn pikku meta functions get <id>) or workflow steps (yarn pikku meta workflows get <id>).

Capability rule: do not introduce new wires of a type whose capabilities.<type> is false unless the user explicitly asked for it.

Stage 2 — State intent in plain English (BEFORE writing code)

Before touching any files, give the user one paragraph stating exactly what you'll do. This is the lightweight "plan" — it is chat, not JSON.

I'll add a todos table via a new migration in sql/, and two pikkuSessionlessFuncs (createTodo, listTodos with readonly: true) in packages/functions/src/functions/. Both expose: true, so they'll be reachable via the auto-generated RPC client and React Query hooks — no HTTP wiring needed. No new dependencies. OK to proceed?

Wait for the user to confirm or redirect. They can ask for changes ("use the existing tasks table" / "make it a queue not http") in normal chat — no schema, no JSON, no ceremony.

Non-interactive runs (auto mode, CI, batch jobs): state intent in one paragraph and proceed without waiting. Surface course corrections promptly in the post-implementation report.

Stage 3 — Branch off

After confirmation, ensure the working tree is clean and create a feature branch off the current default branch (whatever git branch --show-current returns at the start — main, master, develop, all fine):

git status
git switch -c feature/<short-slug>

If the working tree is dirty, stop and ask — never stash silently or overwrite uncommitted work.

Stage 4 — Implement

Write the code as a normal human contributor would. Use the project's existing conventions (look at neighbour files in srcDirectories[0]/functions/ and .../wirings/ for style).

RPC is the default transport

Just write the function with expose: true — that's enough to make it callable. Pikku auto-generates an RPC client (and React Query hooks if the project's clientFiles.reactQueryFile is set) from every exposed function. You do not need an HTTP wiring for callers to reach the function.

Default flow for a feature:

1. Write the function file with expose: true (and readonly: true for reads).
2. Run pikku all — RPC map, fetch client, and React Query hooks are regenerated. Frontends call useListTodos() / mutation.mutate(...) without you wiring anything.

Add an HTTP wiring only when the feature genuinely needs a specific REST shape (third-party callers, webhooks, REST-conventional URLs). Most in-app features don't.

Hard rules that always apply

• expose: true for any function called from a frontend or another service. Without it the RPC client won't generate hooks for it.
• readonly: true for queries. Mark read functions as readonly: true on the function config. The runner uses this to enforce read-only sessions (a write func called under a readonly session is rejected). The RPC layer also uses it to pick useQuery (cacheable) vs useMutation for client hooks. Mutations leave readonly unset (or false).
• kind ⇔ auth coupling for HTTP wirings (when you have one). If the function is pikkuFunc (session-aware), the HTTP wiring needs auth: true. pikkuSessionlessFunc ⇒ auth: false. Mismatching is a hard error (PKU573).
• HTTP method by intent (when you wire HTTP). Reads → GET. Writes → POST/PUT/PATCH/DELETE per REST conventions.
• Workflows. Prefer pikkuWorkflowGraph (DSL) over pikkuWorkflowComplexFunc. mode: 'inline' is sync; 'distributed' is queue-dispatched.
• Auth checks belong on the function or wiring, not in function bodies. Use the permissions field with a pikkuPermission factory.
• Throw typed errors from @pikku/core/errors — NotFoundError, ConflictError, BadRequestError. Never bare Error.
• Migrations are inline SQL files in the project's migrations dir (typically sql/). Use a numbered prefix matching existing files.
• Secrets and env-vars: NEVER process.env. Declare them with wireSecret (sensitive) or wireVariable (non-sensitive) — both with a zod schema for type-safe access. Read with services.secrets.getSecretJSON('NAME') or services.variables.get('NAME'). See the pikku-config skill for the full pattern (including OAuth2 credentials). This applies even in config.ts and singleton service factories.

Conventions to copy from neighbours

Some patterns vary by project; read a neighbour file before writing:

• Function shape: zod schemas as exported consts (CreateTodoInput, CreateTodoOutput) passed to input/output on the func config — vs generic-typed config. Schema name must match codegen expectations (the exported const name = the schema name in generated .gen.json).
• Imports: usually '#pikku' for pikkuFunc / pikkuSessionlessFunc etc. Copy what neighbours do.
• Service usage: e.g. kysely, redis. Look at how an existing function destructures services from its first arg. Check application-types.d.ts to see whether services like kysely are typed (Kysely<DB>) or untyped (Kysely<any>) — that drives whether you can lean on generated DB types or have to coerce manually.
• DB schema namespace: many projects put tables under a CREATE SCHEMA (e.g. app.todos). Read the first migration in sql/ to see the convention; reuse helper functions/triggers (e.g. update_last_updated_at) rather than redefining them.
• HTTP wiring style (only relevant if you're adding one). Two common shapes — match what the project already uses:
  • Per-route wireHTTP({ method, route, func, auth }).
  • Single map: const routes = defineHTTPRoutes({ auth: false, routes: { fooName: { method: 'post', route: '/foo', func: fooFunc } }}); wireHTTPRoutes(routes).

For shared wiring files (e.g. todos.http.ts holding both create and list): create the file with imports if it doesn't exist; append wire calls and add missing imports if it does.

Stage 5 — Verify

Both must complete cleanly for your changes before committing:

yarn pikku all
# Type-check the workspaces you touched:
cd packages/functions && npx tsc --noEmit

Notes on running tsc:

• A root-level yarn tsc may be a no-op in monorepos that don't define a tsc script in each workspace. Don't trust an exit-zero from the root if no actual checking happened — verify by running npx tsc --noEmit in the package(s) you touched.

What "fails" means

Trust the exit code, not the stderr noise. yarn pikku all may print warnings, [PKUxxx] messages, even level: critical log lines, while still exiting 0 — those are pre-existing project state, not your problem. Same for meta context --json: it streams logs to stderr that look scary on a clean baseline. The exit code is the source of truth.

If a command exits non-zero, that's a real failure — fix or stop.

Baseline noise — only your errors matter

Many real-world projects ship with pre-existing warnings or errors (legacy types, version drift, gen-layer messages). Those are not your problem; do not "fix" them.

To distinguish your errors from baseline:

1. Before implementing (Stage 4), capture the baseline:

   yarn pikku all 2>&1 | tee /tmp/pikku-before.log
   

2. After implementing, compare:

   yarn pikku all 2>&1 | tee /tmp/pikku-after.log
   diff /tmp/pikku-before.log /tmp/pikku-after.log
   

A clean diff means your changes introduced no new issues — even if the underlying logs both show pre-existing warnings.

If something genuinely failed because of YOUR change, fix the actual issue. Do not mask errors with as any, @ts-ignore, or --no-verify. If you're stuck, surface the failure to the user — don't hand them a broken branch.

Stage 6 — Commit

git add -A
git commit -m "feat: <short title>"

Stage 7 — Hand off

Tell the user the branch name and how to review. Two options:

• Local review: open the pikku console — the changes view diffs the current branch against main with pikku-aware structure (added functions, new wires, migrations).
• PR review: ask before pushing. Once they confirm, git push -u origin feature/<slug> and surface the PR-create URL.

Do not push without explicit confirmation. Do not merge.

Hard constraints

The skill's allowed-tools does not permit:

• yarn add / npm install / dependency changes (ask the user first)
• yarn dbmigrate (never run migrations against the real DB during planning)
• pikku deploy apply (never deploy)
• secret writes
• network calls beyond what the implementation requires

If the feature genuinely needs any of these, stop and ask with a clear explanation of why and what would change.

Output discipline

• Stage 2 (intent statement) is plain English, one paragraph.
• Between stages, give one-line updates: "Discovered 30 functions, http+queue in use. Drafting intent..." → "Branch feature/todos created, implementing..." → "pikku all clean, tsc clean, committed. Review via console or run git diff main."
• Don't narrate file-by-file. Only surface what's interesting (new patterns, judgment calls, things you suppressed).