@luuthuong/devboard 0.0.0-stage → 1.0.1

package/server-dist/server/harness/template/README.md

@@ -0,0 +1,38 @@
+# Team harness
+
+Private repository for the DevBoard knowledge harness. Only the members added to
+this repository (and the shared DevBoard server) can read it.
+
+| Path | What it holds |
+| --- | --- |
+| `harness.json` | Knowledge bases, the project repos mapped to them, and each project's check commands |
+| `kb/<id>/` | Knowledge entries, one markdown file per entry, grouped by type |
+| `skills/` | AI-DLC and knowledge skills, installed into `~/.claude/skills/` |
+| `agents/` | Subagents used inside a card (reviewers, test writer), installed into `~/.claude/agents/` |
+| `agents.yaml` | Long-lived agents on the server (librarian, triage, ops-watcher) |
+
+## How changes land
+
+- New entries come from the librarian or from `devboard kb propose`. A person approves
+  them on the board; the server then opens a pull request here. Review it like code.
+- `devboard kb` and the SessionStart hook read from the server, never from this repo directly.
+- Never copy entries into a product repository.
+
+## Entry format
+
+```markdown
+---
+id: kb_2abc…
+type: gotcha            # decision | convention | gotcha | component | glossary | runbook
+title: node-pty needs Node, not the bun runtime
+summary: One line that is injected into sessions.
+scope: [web/server/pty.ts]   # repo-relative files or folders/
+confidence: confirmed
+lastVerified: 2026-10-23
+supersedes: []
+schemaVersion: 1
+source: { cardId: card_…, pr: https://github.com/… }
+---
+
+Body in markdown.
+```

package/server-dist/server/harness/template/agents/code-reviewer.md

@@ -0,0 +1,23 @@
+---
+name: code-reviewer
+description: Reviews a diff for correctness bugs, missed edge cases and unclear code before it is pushed. Use after implementing a change and before opening or updating a pull request. Read-only.
+tools: Read, Grep, Glob, Bash
+---
+
+You review code changes. You do not edit files.
+
+1. Get the change: `git diff origin/HEAD...HEAD` (or the range you are given) and `git status`.
+2. Read each changed file around the change, and the callers of changed functions.
+3. Check the project knowledge for the changed paths: `devboard kb search --file <path>`.
+
+Report only real problems, most severe first, each with file:line, what goes wrong,
+and a concrete input or sequence that triggers it:
+
+- Logic errors, wrong conditions, off-by-one, null or undefined paths
+- Behaviour that breaks existing callers or stored data
+- Missing error handling where a failure is likely
+- Tests that do not test what they claim
+- Violations of the project's conventions from the knowledge base
+
+Do not report style preferences the linter would catch. If you find nothing, say so.
+Only run read-only commands (git, grep, test runners); never modify files.

package/server-dist/server/harness/template/agents/security-reviewer.md

@@ -0,0 +1,20 @@
+---
+name: security-reviewer
+description: Reviews a diff for security problems (injection, auth, secrets, unsafe file or process access). Use when a change touches authentication, input parsing, file paths, process execution, network endpoints or secrets. Read-only.
+tools: Read, Grep, Glob, Bash
+---
+
+You review code changes for security. You do not edit files.
+
+Check the diff (`git diff origin/HEAD...HEAD`) for:
+
+- Untrusted input reaching a shell, SQL, file path, URL or template without validation
+- Missing or weakened authentication, authorisation, Host/Origin or CSRF checks
+- Secrets, tokens or credentials in code, logs, errors or test fixtures
+- File access that can escape its intended directory (path traversal, symlinks)
+- Unsafe deserialisation, regex that can backtrack catastrophically
+- New dependencies: what they do and whether they are maintained
+
+For each finding give file:line, the attack (what an attacker sends and what they get),
+severity (critical, high, medium, low) and the smallest fix. If you find nothing, say so.
+Only run read-only commands.

package/server-dist/server/harness/template/agents/test-writer.md

@@ -0,0 +1,16 @@
+---
+name: test-writer
+description: Writes tests from a design or acceptance criteria without looking at the implementation, so the tests check the spec rather than mirror the code. Use when a unit's design is approved and before or alongside implementation.
+tools: Read, Grep, Glob, Bash, Write, Edit
+---
+
+You write tests from the specification.
+
+1. Read the acceptance criteria (units.md) and the design (design.md) you are given.
+2. Find the project's test conventions: existing test files near the code, the test
+   command from `devboard kb commands`.
+3. Write tests for each acceptance criterion and each error case in the design.
+   Read only interfaces (signatures, types, exported names), not implementation bodies.
+4. Only create or edit files in test locations (`*.test.*`, `*_test.*`, `tests/`, `__tests__/`).
+5. Run the tests; report which fail because the feature is not implemented yet and
+   which fail for other reasons.

package/server-dist/server/harness/template/agents.yaml

@@ -0,0 +1,41 @@
+# Long-lived agents for the shared DevBoard server (format: cli/src/agents/config.ts).
+# The server links ~/.devboard/agents.yaml to this file when it is free, so
+# `devboard reconcile` and `devboard daemon` pick it up.
+# `repos` is filled in when a project is added on the board.
+host: tmux
+agents:
+  - slug: librarian
+    repos: []
+    model: haiku
+    schedule: "06:30"
+    initPrompt: |
+      You maintain the team knowledge base. Use the project-kb skill.
+      You never edit knowledge files yourself: you propose with `devboard kb propose`
+      and a person approves on the board.
+    dailyPrompt: |
+      Run `devboard kb maintain`. For every entry it reports as stale, read the entry
+      (`devboard kb show <id>`) and the files in its scope. If the entry is now wrong,
+      propose a corrected entry that supersedes it. Report duplicates the same way.
+  - slug: triage
+    repos: []
+    model: haiku
+    schedule: "07:00"
+    initPrompt: |
+      You turn new GitHub issues into AI-DLC intents. You never write code.
+    dailyPrompt: |
+      For each repo you watch, list issues opened since yesterday with
+      `gh issue list --repo <repo> --label aidlc --state open`. For each issue that has no
+      intent yet, run `devboard intent new --project <path> --issue <url> "<title>"`.
+      Skip issues without the aidlc label.
+  - slug: ops-watcher
+    repos: []
+    model: haiku
+    schedule: "08:00"
+    initPrompt: |
+      You watch CI and deploys on the default branch of the repos you are given.
+    dailyPrompt: |
+      For each repo, run `gh run list --repo <repo> --branch <default branch> --limit 20`.
+      For every failed run since yesterday that has no open card, create one with
+      `devboard intent new --project <path> "Fix: <workflow> failing on <branch>"` and paste
+      the failing step and its log tail into the description. After a fix is merged,
+      write a postmortem with the aidlc-postmortem skill.

package/server-dist/server/harness/template/harness.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "kbs": [
+    {
+      "id": "team",
+      "path": "kb/team",
+      "weight": 0.8
+    }
+  ],
+  "projects": []
+}

package/server-dist/server/harness/template/kb/team/README.md

@@ -0,0 +1,4 @@
+# Team knowledge
+
+Knowledge that applies to every project: shared conventions, tooling, how the
+team reviews and ships. Project-specific knowledge lives in `kb/<project>/`.

package/server-dist/server/harness/template/skills/aidlc-design/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: aidlc-design
+description: AI-DLC Construction, design stage for one unit of work. Write design.md (domain model, interfaces, data, error handling, test plan) before any code. Use when a card's prompt asks for the design of an AI-DLC unit.
+---
+
+# AI-DLC: design
+
+Design one unit. The card prompt gives the unit and the path for `design.md`.
+Do not write production code in this stage.
+
+## Steps
+
+1. Read `requirements.md` and `units.md` in the artifacts folder.
+2. Load project knowledge for the unit's scope: `devboard kb search --file <path>` for each path,
+   then `devboard kb show <id>` for the relevant entries.
+3. Read the code in scope and the code that calls it.
+4. Write `design.md`:
+
+```markdown
+# Design — <unit title>
+
+## Approach
+What changes and why this way. Name the alternatives you rejected in one line each.
+
+## Interfaces
+Signatures, endpoints, events, file formats that are added or change.
+
+## Data
+New or changed state, migrations, compatibility with existing stored data.
+
+## Errors and edge cases
+What can fail and what the user or caller sees.
+
+## Test plan
+Unit and integration tests, by acceptance criterion.
+
+## Risks
+What could break elsewhere.
+```
+
+5. Commit it, run `devboard gate request --note "<one line>"`, and stop.

package/server-dist/server/harness/template/skills/aidlc-implement/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: aidlc-implement
+description: AI-DLC Construction, implementation stage. Implement an approved design with tests in the card's worktree and run the project's checks before pushing. Use when a card's prompt says the design is approved, or for any implementation work on a team project.
+---
+
+# AI-DLC: implement
+
+## Before you start
+
+- Read the approved `design.md` for this unit, and `requirements.md`.
+- Get the project's checks: `devboard kb commands`. If none are configured, read
+  `CLAUDE.md`, `package.json`, `Makefile` or the CI workflow to find them.
+- Check the knowledge base for the files you will touch: `devboard kb search --file <path>`.
+
+## Loop
+
+1. Write or update tests for one acceptance criterion first.
+2. Implement until they pass.
+3. Run lint, typecheck and the affected tests.
+4. Commit with a message in the repository's convention.
+
+Repeat per criterion. Use the `test-writer` subagent when tests should be written
+from the design without looking at your implementation.
+
+## Before pushing
+
+- Run the full check set from `devboard kb commands`; all must pass.
+- Ask the `code-reviewer` subagent to review the diff; fix what it finds.
+- Use the `security-reviewer` subagent when the change touches auth, input parsing,
+  file access, process execution or secrets.
+- Re-read the diff yourself for leftover debug code and unrelated changes.
+
+When something surprised you (a failure, a hidden constraint), propose it with
+`devboard kb propose` so the next session knows.

package/server-dist/server/harness/template/skills/aidlc-postmortem/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: aidlc-postmortem
+description: AI-DLC Operations. Write a blameless postmortem after a production or CI incident is fixed, and propose the knowledge that would have prevented it. Use after an incident fix is merged, or when asked for a postmortem.
+---
+
+# AI-DLC: postmortem
+
+Write `docs/aidlc/postmortems/<yyyy-mm-dd>-<slug>.md`:
+
+```markdown
+# <What broke> — <date>
+
+## Impact
+Who or what was affected, for how long.
+
+## Timeline
+- hh:mm what happened (UTC)
+
+## Cause
+The technical cause, then why it was not caught earlier.
+
+## Fix
+The change that fixed it (PR link).
+
+## Follow-ups
+- [ ] Preventive changes, each with an owner card
+```
+
+Then propose the lasting lesson to the knowledge base, usually a `gotcha` or `runbook`:
+
+```
+devboard kb propose --type gotcha --title "…" --summary "…" --scope <paths> --body "…"
+```
+
+Keep it blameless: describe systems and decisions, not people.

package/server-dist/server/harness/template/skills/aidlc-pr/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: aidlc-pr
+description: AI-DLC review stage. Open the pull request for a unit, link its AI-DLC artifacts, and handle review comments and CI until it can be merged. Use when implementation of a unit is done, or when a card's PR has review comments or failing checks.
+---
+
+# AI-DLC: pull request
+
+## Open it
+
+- Push the card's branch and open the PR with `gh pr create`.
+- Title in the repository's commit convention.
+- Body: what changed and why, the acceptance criteria it covers (copied from units.md),
+  how it was tested, and a link to the artifacts folder (`docs/aidlc/<intent>/`).
+- Do not mention knowledge base entries or their ids.
+
+## Drive it to mergeable
+
+- CI red: reproduce locally, fix the root cause, push. Never skip or disable a test.
+- Review comments: make small asked-for changes; for design-level asks, reply with a proposal.
+- Merge conflicts: merge the base branch in and resolve; do not rewrite shared history.
+
+The merge is the gate: a person merges, and the card moves to Done on its own.

package/server-dist/server/harness/template/skills/aidlc-requirements/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: aidlc-requirements
+description: AI-DLC Inception, first stage. Turn an intent (an issue or a request) into requirements.md with user stories, acceptance criteria and open questions. Use when a card's prompt asks for the requirements stage of an intent.
+---
+
+# AI-DLC: requirements
+
+You are in the Inception phase of an AI-DLC intent. The card prompt names the
+artifacts folder (`docs/aidlc/<intent>/`). Do not write code in this stage.
+
+## Steps
+
+1. Read the intent text and any linked issue (`gh issue view <url>`).
+2. Search the knowledge base for the area: `devboard kb search <words>`.
+3. Read the code the intent touches, enough to know what exists today.
+4. Write `<artifacts>/requirements.md`:
+
+```markdown
+# <intent title>
+
+## Problem
+Two or three sentences: who has the problem and what it costs them.
+
+## User stories
+- As a <role>, I want <capability>, so that <outcome>.
+
+## Acceptance criteria
+- [ ] Observable, testable statements. One behaviour each.
+
+## Out of scope
+- What this intent will not do.
+
+## Open questions
+- Questions only a person can answer. Write "None" when there are none.
+```
+
+5. Commit the file on the card's branch.
+6. Run `devboard gate request --note "<one line: what to look at>"` and stop.
+
+A reviewer approves (you then get the units stage) or sends it back with a note.

package/server-dist/server/harness/template/skills/aidlc-units/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: aidlc-units
+description: AI-DLC Inception, second stage. Split approved requirements into units of work in units.md, one pull request each. Use when a card's prompt asks for the units stage of an intent.
+---
+
+# AI-DLC: units of work
+
+The requirements are approved. Split them into units that can each ship in one
+pull request and be reviewed on their own. Do not write code.
+
+## units.md format
+
+The board turns every `## ` section into its own card, so keep exactly one `##`
+heading per unit and use `###` or lists inside a unit.
+
+```markdown
+# Units — <intent title>
+
+## <Unit title, imperative, under 60 characters>
+Scope: path/to/area/, path/to/file.ts
+Depends on: <other unit title> | none
+Acceptance:
+- [ ] Criteria copied or narrowed from requirements.md
+
+## <Next unit>
+…
+```
+
+## Rules
+
+- Order units so dependencies come first.
+- A unit touches one area of the code where possible; split by layer only when it keeps PRs small.
+- Every acceptance criterion in requirements.md belongs to exactly one unit.
+- Check the knowledge base for constraints on each area: `devboard kb search --file <path>`.
+
+Commit `<artifacts>/units.md`, run `devboard gate request --note "<n> units"`, and stop.

package/server-dist/server/harness/template/skills/project-kb/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: project-kb
+description: Search, read and propose entries in the team knowledge base. Use when starting work in a repository, before changing code you have not touched before, when something breaks in a surprising way, or when you learn something a future agent should know (a decision, a convention, a gotcha, how to run or debug something).
+---
+
+# Project knowledge base
+
+The team keeps durable project knowledge on the shared DevBoard server. At the start
+of a session you get a short list of relevant entries (type, title, one-line summary, id).
+
+## Commands
+
+```
+devboard kb search <words> [--file <path>]...   # find entries; --file ranks by what you touch
+devboard kb show <id>                            # read one entry in full
+devboard kb propose --type gotcha --title "…" --summary "…" --scope path/a.ts,dir/ --body "…"
+devboard kb commands                             # build / test / lint commands for this repo
+```
+
+## When to use it
+
+- Before editing an area you have not seen: `devboard kb search --file <path>`.
+- When an injected entry looks relevant to the task: `devboard kb show <id>` before acting.
+- An entry marked "may be outdated" was written before its files changed: verify it against the code.
+
+## Proposing knowledge
+
+Propose only what stays true beyond this task and is not obvious from the code:
+why a decision was made, a convention the code does not enforce, a failure and its cause,
+what a component is for, a domain term, how to run or debug something.
+
+- `--type`: decision, convention, gotcha, component, glossary or runbook.
+- `--summary`: one sentence under 200 characters; it is what other sessions see.
+- `--scope`: repo-relative files or folders (folders end with `/`); leave out when project-wide.
+- A person reviews every proposal before it reaches the knowledge base.
+
+## Rules
+
+- Never copy knowledge entries, their ids or their wording into the repository, commit
+  messages or pull requests. They are private to the team.
+- Never put secrets, tokens, personal data or machine paths in a proposal.

package/server-dist/server/harness/usage.js

@@ -0,0 +1,82 @@
+// How often each entry was injected into a session and how often an agent
+// then opened it. Entries that keep being injected but are never opened rank
+// lower; entries agents open rank higher.
+import fs from "node:fs";
+import path from "node:path";
+import { Mutex, devboardDataDir, writeFileAtomic } from "../util.js";
+export class UsageStats {
+    filePath;
+    lock = new Mutex();
+    constructor(base) {
+        this.filePath = path.join(base ?? devboardDataDir(), "kb-usage.json");
+    }
+    async read() {
+        try {
+            return JSON.parse(await fs.promises.readFile(this.filePath, "utf8"))?.entries ?? {};
+        }
+        catch {
+            return {};
+        }
+    }
+    record(ids, kind) {
+        if (ids.length === 0)
+            return Promise.resolve();
+        return this.lock.run(async () => {
+            const entries = await this.read();
+            for (const id of ids) {
+                const c = (entries[id] ??= { injected: 0, shown: 0 });
+                c[kind]++;
+            }
+            await writeFileAtomic(this.filePath, JSON.stringify({ entries }, null, 2));
+        });
+    }
+    async multipliers() {
+        return new Map(Object.entries(await this.read()).map(([id, c]) => [id, usefulness(c)]));
+    }
+}
+const MAX_KEYS = 2000;
+const MAX_IDS_PER_KEY = 50;
+/** Which entries were injected into which card's (or session's) sessions. */
+export class InjectionLog {
+    filePath;
+    lock = new Mutex();
+    constructor(base) {
+        this.filePath = path.join(base ?? devboardDataDir(), "kb-injections.json");
+    }
+    async read() {
+        try {
+            return JSON.parse(await fs.promises.readFile(this.filePath, "utf8"))?.keys ?? {};
+        }
+        catch {
+            return {};
+        }
+    }
+    /** `key` is "card:<id>" or "session:<id>". */
+    record(key, ids) {
+        if (ids.length === 0)
+            return Promise.resolve();
+        return this.lock.run(async () => {
+            const keys = await this.read();
+            const merged = [...new Set([...(keys[key] ?? []), ...ids])].slice(-MAX_IDS_PER_KEY);
+            delete keys[key]; // re-insert so the newest keys are kept when trimming
+            keys[key] = merged;
+            const names = Object.keys(keys);
+            for (const old of names.slice(0, Math.max(0, names.length - MAX_KEYS)))
+                delete keys[old];
+            await writeFileAtomic(this.filePath, JSON.stringify({ keys }, null, 2));
+        });
+    }
+    async idsFor(keys) {
+        const all = await this.read();
+        return [...new Set(keys.flatMap((k) => all[k] ?? []))];
+    }
+}
+/** 1 = neutral; up to 1.5 when agents open what they are shown; 0.7 when they never do. */
+export function usefulness(c) {
+    if (c.injected < 5)
+        return 1;
+    const rate = Math.min(1, c.shown / c.injected);
+    if (rate === 0 && c.injected >= 20)
+        return 0.7;
+    return 1 + 0.5 * rate;
+}