chamba 0.7.0 → 0.9.0

package/templates/skills/dx-spec-config/SKILL.md

@@ -1,313 +0,0 @@
----
-name: dx-spec-config
-description: View and change the settings and principles the dx-spec skills honor - commit style, saved planning answers, and the engineering principles - and define the one-time setup the other dx-spec skills offer at start. User-invoked only.
-disable-model-invocation: true
----
-
-# dx-spec config - the user's preferences
-
-This skill runs when the user types `/dx-spec-config`. It never starts on its own.
-
-The skill owns one file: the principles file beside the specs.
-It writes that file the first time, it runs a wizard to change it, and it runs a doctor that checks it against the shape below.
-`/dx-spec` and `/dx-spec-execute` only read it.
-The init flow is the one flow this skill offers the other two.
-
-## The web session
-
-Every skill in this family runs inside a chamba web session.
-Check for one before anything else:
-
-```
-specs stages
-```
-
-The answer holds `root` - the directory the Specs tab serves - and the stage catalog.
-A refusal means there is no pane.
-Say this and stop:
-
-> This works in the chamba web session, where the Specs tab holds your work. Open the browser window this container printed at start, or run `webterm` in the terminal to get the address again. Then run `/dx-spec-config` there.
-
-Start no flow, and offer no substitute.
-
-## Asking questions
-
-The questions in this skill belong to no piece of work, so they do not go on the Specs tab.
-The tab's forms belong to one spec, and settings belong to none.
-Ask them with `AskUserQuestion`.
-When that tool is absent, or refuses a call, ask the question as a normal message and end your turn.
-Then wait. Do not do the thing the question was there to confirm.
-
-Write a question whose options do not depend on the work as a fenced block tagged `question`, and ask it exactly as written.
-
-````markdown
-```question
-Question: <the question text, verbatim>
-Header: <the short chip label, verbatim>
-- <option label>
-  <option description>
-- <option label>
-  <option description>
-```
-````
-
-How to read a block:
-
-- Copy the question text, the header, the labels, the descriptions and their order exactly.
-- Angle brackets mark the parts you fill in.
-- A line marked `only when ...` is conditional. Every other line is always there.
-- Never reword a block to fit the moment. Never add an option.
-- `AskUserQuestion` adds its own free-text choice, so no block carries an option that only means "something else".
-
-Every question shows 2 options at least and 4 options at most.
-Put the recommended option first, and end its label with `(Recommended)`.
-Keep labels short, and put the reasoning in the descriptions.
-Write for someone who has never used these skills.
-
-## The specs root
-
-`specs stages` answers with `root`.
-That is the directory the Specs tab serves, and every path in this family resolves against it.
-The principles file is `<root>/principles.md`.
-
-## The principles file
-
-`<root>/principles.md` is plain markdown.
-It holds a settings section and a principles section, and nothing else.
-
-The settings sit under a `## Settings` heading, one `- <key>: <value>` bullet each, under one note line that points at `/dx-spec-config`.
-The principles sit under a `## Principles` heading, one `- <principle>` bullet each.
-The file carries no explanation of a setting, no guidance on writing a principle, and no examples.
-Every run of every skill in this family reads this file, so it holds only what an agent must honor.
-The meaning of each setting lives here, in the skill that writes the file.
-
-What each setting holds:
-
-- `commit_style` - the shape of every commit message this family makes. `default` names the default style below. Any other value is a plain description of the project's own shape, with an example message in it.
-- `commit_mode` - a saved answer to "should the run commit as it goes?". `prompt` keeps the question, `current-branch` commits on the current branch, `new-branch` commits on a new branch, and `no-commits` leaves the changes in the working tree.
-- `commit_grouping` - a saved answer to "how are those commits grouped?". `prompt` keeps the question, `per phase` commits each phase, and `single` commits once at the end. This setting counts only when the run commits at all.
-- `branch_naming` - the branch name pattern for `commit_mode: new-branch`. `<slug>` in the pattern becomes the spec's own slug.
-
-The principles section holds plain engineering principles that every run honors best-effort.
-A principle states its reason when the reason is not obvious.
-A principle states its own scope when it does not apply everywhere.
-When the project's own documents already carry a rule, the principle points at that rule and declares it binding.
-It does not restate the rule.
-The section ships empty, so an empty section means no principles.
-Use this form:
-
-```markdown
-- Always recommend two code reviewers at least in an execution plan, because one reviewer shares too many blind spots with the author.
-- Never add a dependency without asking first: a dependency is a cost the project carries for years.
-```
-
-A saved answer skips its question, and says nothing.
-The execution-plan stage still records the resolved `Commits:` and `Branch:` lines in `PLAN.md`, whatever their source.
-The plan gate still shows the whole setup, so the user can make an exception for one spec there.
-That exception changes that plan alone, and never this file.
-
-The shipped template is `references/principles-template.md`, beside this file.
-A fresh file starts as a copy of it.
-
-## The default commit style
-
-The default style is the spec name, then a colon, then what the commit did:
-
-```
-user-preferences: spec ready
-user-preferences: phase 02 - the consuming skills
-user-preferences: review fixes
-```
-
-This skill and its template are the only places that spell the pattern out.
-Every other mention of it says "the default style".
-
-The commits this skill makes use `dx-spec` in place of the spec name: `dx-spec: set up config` and `dx-spec: update config`.
-A `commit_style` that is not `default` restyles these the same as any other message.
-
-When `commit_style` describes a type-prefixed convention, two families apply:
-
-- A spec-level commit touches only spec files, so its type is fixed - `docs`, for example.
-- A work-level commit carries code, so its type comes from what the phase did.
-
-## The bootstrap
-
-Before its first step, `/dx-spec` and `/dx-spec-execute` do this:
-
-1. Read `root` from `specs stages`.
-2. Read `<root>/principles.md` when it is there, and take what parses: the settings it knows, and the principles bullets.
-3. When a setting is missing, unreadable, or holds a value this file does not list, use its default. Say so once, in one line, and name `/dx-spec-config` as where it gets sorted out. Repair nothing here: a run the user is waiting on is not the place to fix a settings file.
-4. With no file there at all, ask the question below. On "set it up now", run the init flow before the run continues.
-5. Apply the settings and the principles for the rest of the run.
-
-```question
-Question: You have no settings file for this yet. Should I set one up now?
-Header: Setup
-- Set it up now (Recommended)
-  A few questions about how you like to work - how commits are written, and what I may do without asking - and I write the file before we carry on. You answer them once.
-- Carry on without it
-  I use the built-in defaults for this run and ask again next time. You can also set it up whenever you like, with /dx-spec-config.
-```
-
-A file that reads cleanly produces no message at all.
-The init flow is the only flow a bootstrap runs.
-Checking the file, repairing it and changing it all belong to a direct run of this skill.
-
-## Init flow
-
-This flow runs when a direct `/dx-spec-config` run finds no principles file, and when a bootstrap offers it and the user agrees.
-
-1. Send one short intro message: this family keeps a small settings and principles file beside the specs, this is its one-time setup, and anything chosen here changes later through `/dx-spec-config` or by editing the file.
-2. Work out the project's commit style. Read the project's own commit rules and its recent commit subjects. A clear shape - a type prefix, a ticket key, any consistent pattern - becomes the first option below, written in plain words with an example message from this project. Drop that option when the project shows no consistent shape. A commit this family made in the default style is not a project convention.
-3. Ask the three questions below in one `AskUserQuestion` call.
-
-```question
-Question: How should the commits I make be written?
-Header: Commit style
-- <the project's own style, in a few words> (Recommended) (only when the project's commits or rules show a clear shape)
-  <the shape found, in plain words, with an example message from this project>.
-- The default style
-  The spec name, a colon, then what the commit did.
-- Conventional prefixes (only when the first option is not itself a type-prefix shape)
-  A type prefix, then what the commit did: "feat: ...", "fix: ...", "docs: ...", and so on.
-```
-
-When the first option is absent, the default style comes first and carries the marker.
-Save the answer as `commit_style`: `default` for the default style, and otherwise a plain description of the shape with an example message in it.
-
-```question
-Question: Should runs save their work with git commits as they go?
-Header: Commits
-- Decide per piece of work (Recommended)
-  Each execution plan asks this when it is written.
-- Yes, on the current branch
-  Every run commits as it goes, on whatever branch is checked out.
-- Yes, on a new branch
-  Every run commits on a branch of its own, named by a pattern you can change later.
-- No commits
-  Runs leave their changes in your working folder for you to handle.
-```
-
-```question
-Question: And when a run commits, how should the commits be grouped?
-Header: Grouping
-- Decide per piece of work (Recommended)
-  Each execution plan asks this when it is written.
-- One commit per phase
-  Each finished phase is committed on its own.
-- A single commit
-  All the work lands in one commit at the end.
-```
-
-4. Ask the question below in a second `AskUserQuestion` call, right after those three. It gets its own call, because the answer starts a task and leads to another question.
-
-```question
-Question: Should I read your project now and draft the principles I should follow?
-Header: Principles
-- Draft them from the project (Recommended)
-  I read your rule documents, the README, the lint and CI setup, and recent commits, and propose a short list for you to look over.
-- Start with none
-  The file is written with an empty principles section. You can add principles any time through /dx-spec-config, which offers the same draft from your project.
-```
-
-On "draft them from the project": read `CLAUDE.md` and `AGENTS.md`, the README, the lint and CI configs, and recent commits.
-Draft the principles from what they show.
-Point at a rule the project already documents, and declare it binding, rather than restating it.
-Write down the undocumented conventions alone.
-Keep the draft to five or six principles, because every run reads this file.
-Write nothing to disk in this step. Step 5 writes it.
-
-On "start with none": keep the template's empty principles section for step 5.
-
-5. Write `<root>/principles.md` once: the template, with each setting's value replaced by the answer, and the principles section either drafted or empty.
-6. Only when you drafted principles, ask the user to read them:
-
-```question
-Question: I wrote the principles into <root>/principles.md - please read them there. Keep them as they are?
-Header: Principles
-- Keep them (Recommended)
-  The file stays as it is.
-- Change them
-  Tell me what to add, reword or drop. I rewrite the principles section and ask again.
-```
-
-On "change them": rewrite the section from what the user typed, then ask this question again. Loop until they keep it.
-
-7. Offer the commit gate below, with the message `dx-spec: set up config` in the confirmed style.
-8. Carry on with whatever the skill was invoked to do.
-
-```question
-Question: Should I commit your principles file to git?
-Header: Commit file
-- Commit it (Recommended)
-  I commit only <root>/principles.md, with the message "<the composed message>". I never push.
-  (only when the working tree holds unrelated changes) Everything else you have changed is left exactly as it is.
-- Don't commit
-  The file stays in your working folder for you to handle.
-```
-
-On "commit": stage the principles file by path, and commit it. Commit only. Never push.
-
-## The doctor
-
-The doctor is the check a direct `/dx-spec-config` run makes on an existing file.
-It is the one place file trouble is dealt with.
-No other skill runs it, and it never runs during someone else's work.
-
-Compare the user's file against the shape above, by meaning rather than by bytes:
-
-- A setting the shape has and the file lacks: propose adding it with its default, and say what it does.
-- A setting whose value is not one this file lists: say what the setting does, name the values that exist, and ask which one is meant.
-- A setting the file holds that this shape no longer has: propose dropping it, because nothing reads it.
-- Text this shape does not have - an opening note, an explanation under a setting, example principles: propose dropping it, because every run reads this file and that material belongs in this skill. Never touch a line under `## Principles` this way. A principle belongs to the user, however it is worded.
-- A whole section the file lacks: treat it as something the user removed. Name what is on offer, and put back only what they ask for.
-- A file that does not read as markdown at all: say so plainly, and offer to write a fresh one, keeping every setting and principle the current file still lets you read.
-
-Nothing here is an error, and nothing is applied without asking.
-Say what you found in one short message, then ask:
-
-```question
-Question: I compared your settings file with the shape this version expects: <what differs, in a line each>. Bring it up to date?
-Header: Settings file
-- Apply these (Recommended)
-  I make those changes. Every setting you chose and every principle you wrote stays exactly as it is.
-- Leave it as it is
-  Nothing is changed, and everything keeps working on what your file already says.
-```
-
-A partial answer - one change and not another - comes through free text.
-Write into the file whatever the user accepts.
-The commit gate at the end of the run covers it.
-
-## Running directly - the wizard
-
-When the user types `/dx-spec-config`, read `root` and look at `principles.md`:
-
-- No file: run the init flow, minus its last step, and stop there. A file just written needs no doctor.
-- A file there: run the doctor, then the wizard below.
-
-Show one short message: the commit style, the saved planning answers, and a short summary of the principles.
-When the section is empty, say plainly that no principles are written yet.
-Then ask:
-
-```question
-Question: Anything you want to change?
-Header: Settings
-- Nothing - keep it as it is (Recommended)
-  The wizard ends here.
-- The commit style
-  How the commits I make are written. I can also work out a fresh proposal from your project's commits.
-- The planning answers
-  Whether runs commit as they go, how commits are grouped, and the branch name pattern.
-- The principles
-  The principles every run reads at start and honors. I show you the ones you have, and you add, reword or drop them by typing what you want.
-```
-
-A setting change reuses the init-flow question for that setting.
-The commit style change offers the same fresh derivation the init flow makes.
-The principles area offers the same derivation too.
-Change the principles and the branch pattern through free text: the user types, you restate, they confirm.
-After each change, ask this question again, so several things change in one run.
-
-When the doctor or the wizard changed anything, write the file, then end with the commit gate from the init flow and the message `dx-spec: update config`.
-When nothing changed, end without touching the file.

package/templates/skills/dx-spec-config/references/principles-template.md

@@ -1,12 +0,0 @@
-# Principles
-
-## Settings
-
-Run `/dx-spec-config` to change these.
-
-- commit_style: default
-- commit_mode: prompt
-- commit_grouping: prompt
-- branch_naming: spec/<slug>
-
-## Principles

package/templates/specs.sh

@@ -1,106 +0,0 @@
-#!/usr/bin/env bash
-# specs - move a piece of work through the Specs tool in this session's web pane.
-# Baked into the image at /usr/local/share/chamba/specs.sh, on PATH as `specs`.
-#
-# The agent's half of the coordination channel. The pane writes a file and types one line into this terminal;
-# these verbs are how the work moves the other way. Everything they change is a file in the spec directory,
-# so every exchange is something git can see.
-#
-# The caller says who it is by its own pid and nothing more, exactly as `webpane` does. The server walks up
-# the process tree from there to a session it started, and refuses a caller that is not in one.
-set -euo pipefail
-
-CONTAINER_PORT="${WEBTERM_PORT:-3899}"
-KEY_FILE="${WEBTERM_KEY_FILE:-/tmp/webterm.key}"
-
-usage() {
-    cat <<'TEXT'
-Usage: specs <verb> [<spec>] < payload.json
-
-Verbs:
-  stages                 Where the specs live, and every stage a protocol may hold.
-  state    <spec>        Where the work stands: protocol, activity, what awaits the user.
-  intake   [<spec>]      File a new piece of work. { name, text, attachments }
-  propose  <spec>        Recommend a protocol. { stages: [{ id, recommended, why }], note }
-  await    <spec>        Declare a gate or a round. { id, kind, title, file, payload }
-  post     <spec>        Say what is happening. { kind: activity | stage | phase | status | note, ... }
-  review   <spec>        Post a round of quality review. { round, verdict, findings, judgments }
-  answers  <spec>        Read back what the user answered. { id }
-
-A payload is JSON on stdin, where the verb takes one. The answer is JSON on stdout.
-TEXT
-}
-
-VERB="${1:-}"
-SPEC="${2:-}"
-
-case "$VERB" in
-    "" | -h | --help)
-        usage
-        exit 0
-        ;;
-esac
-
-if [ ! -r "$KEY_FILE" ]; then
-    echo "specs: the web interface is not running in this container, so there is no pane to tell." >&2
-    exit 1
-fi
-
-# A payload only where one was piped in. A verb that takes none is called with nothing on stdin, and waiting
-# for a terminal to close would hang the agent rather than answer it.
-PAYLOAD="null"
-if [ ! -t 0 ]; then
-    PIPED="$(cat)"
-    if [ -n "$PIPED" ]; then
-        PAYLOAD="$PIPED"
-    fi
-fi
-
-BODY_FILE="$(mktemp)"
-REQUEST_FILE="$(mktemp)"
-trap 'rm -f "$BODY_FILE" "$REQUEST_FILE"' EXIT
-
-# The request is composed with jq so the payload stays JSON rather than being spliced into a string. jq is in
-# the image; without it there is no safe way to build this, so the helper says so instead of guessing.
-if ! command -v jq >/dev/null 2>&1; then
-    echo "specs: jq is not in this container, and the request cannot be composed without it." >&2
-    exit 1
-fi
-
-if ! jq -n --arg verb "$VERB" --arg spec "$SPEC" --argjson payload "$PAYLOAD" \
-    '{ verb: $verb, spec: $spec, payload: $payload }' >"$REQUEST_FILE" 2>/dev/null; then
-    echo "specs: the payload on stdin is not JSON." >&2
-    exit 1
-fi
-
-# $$ is this script's own pid. The server climbs from it to whichever session started it.
-STATUS="$(
-    curl -sS -o "$BODY_FILE" -w '%{http_code}' \
-        --connect-timeout 3 --max-time 30 \
-        -X POST \
-        -H "Content-Type: application/json" \
-        -H "X-Webterm-Key: $(head -n 1 "$KEY_FILE")" \
-        -H "X-Specs-Pid: $$" \
-        --data-binary "@${REQUEST_FILE}" \
-        "http://127.0.0.1:${CONTAINER_PORT}${WEBTERM_SPECS_AGENT_PATH:-/specs/agent}" 2>/dev/null
-)" || {
-    echo "specs: could not reach the web interface on this container's port ${CONTAINER_PORT}." >&2
-    exit 1
-}
-
-if [ "$STATUS" = "200" ]; then
-    jq . <"$BODY_FILE"
-    exit 0
-fi
-
-REASON="$(jq -r '.error // empty' <"$BODY_FILE" 2>/dev/null)"
-if [ -z "$REASON" ]; then
-    case "$STATUS" in
-        403) REASON="the key on disk is not the one the interface is using" ;;
-        409) REASON="this is not running inside a web session" ;;
-        413) REASON="the payload is too large" ;;
-        *) REASON="the interface answered ${STATUS}" ;;
-    esac
-fi
-echo "specs: nothing was done - ${REASON}." >&2
-exit 1