coulomb/binky-control
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Seeded initial INTENT

Browse source
This commit is contained in:
tegwick 2026-07-16 02:34:24 +02:00
parent aabf9a2a72
commit 67d735ddec
7 changed files with 2648 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

27
.custodian-brief.md Normal file
View file

@ -0,0 +1,27 @@
<!-- custodian-brief: generated by statehub register; fix-consistency may replace this file -->
# Custodian Brief - binky-control
**Project:** binky-control
**Domain:** infotech
**State Hub:** http://127.0.0.1:8000
**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a`
## Open Workplans
### Bootstrap State Hub integration
Workplan file: `workplans/BINKY-WP-0001-statehub-bootstrap.md`
Open tasks:
- T01 - Review generated integration files
- T02 - Verify local developer workflow
- T03 - Seed first real workplan
## Session Start
1. Read `INTENT.md`, `SCOPE.md`, and `AGENTS.md`.
2. Check inbox: `GET /messages/?to_agent=binky-control&unread_only=true`.
3. Scan `workplans/`.
4. Update task statuses in workplan files as work progresses.
Last generated: 2026-07-16

6
.gitignore vendored
View file

@ -162,3 +162,9 @@ cython_debug/
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
#.idea/
# state-hub: track .claude/rules
# Claude Code local state (track shared rules; ignore machine-specific files)
.claude/*
!.claude/rules/
!.claude/rules/*.md

180
AGENTS.md Normal file
View file

@ -0,0 +1,180 @@
# binky-control — Agent Instructions
## Repo Identity
**Purpose:** binky-control is the company control plane ("company brain") for Binky Hedgehog GmbH's transformation into Operational Knowledge GmbH, holding the canon (intent, policies, plans), work queues, and registries that give agents and the solo founder shared situational awareness with executable next steps.
**Domain:** infotech
**Repo slug:** binky-control
**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a`
**Workplan prefix:** `BINKY-WP-`
---
## State Hub Integration
The Custodian State Hub tracks work across all domains. Interact via HTTP REST —
there is no MCP server for Codex agents.
| Context | URL |
|---------|-----|
| Local workstation | `http://127.0.0.1:8000` |
| Remote via tunnel | `http://127.0.0.1:18000` |
| Optional local edge relay | http://127.0.0.1:18080 |
When an operator has enabled the edge relay, set API_BASE to the relay URL.
Queueable writes return an explicit queued receipt if the central hub is
unreachable. Treat that as pending local evidence, then ask the operator to run
statehub outbox status/replay after connectivity returns.
### Orient at session start
```bash
# Offline brief — works without hub connection
cat .custodian-brief.md
# Active workplans for this domain
curl -s "http://127.0.0.1:8000/workplans/?topic_id=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" \
| python3 -m json.tool
# Check inbox
curl -s "http://127.0.0.1:8000/messages/?to_agent=binky-control&unread_only=true" \
| python3 -m json.tool
```
Mark a message read:
```bash
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
-H "Content-Type: application/json" -d '{}'
```
### Log progress (required at session close)
```bash
curl -s -X POST http://127.0.0.1:8000/progress/ \
-H "Content-Type: application/json" \
-d '{
"summary": "what was done",
"event_type": "note",
"author": "codex",
"workplan_id": "<uuid>",
"task_id": "<uuid>"
}'
```
Omit `workplan_id` / `task_id` when not applicable.
### Update task status
```bash
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
-H "Content-Type: application/json" \
-d '{"status": "progress"}'
# values: wait | todo | progress | done | cancel
```
### Flag a task for human review
```bash
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
-H "Content-Type: application/json" \
-d '{"needs_human": true, "intervention_note": "reason"}'
```
---
## Session Protocol
**Start:**
1. `cat .custodian-brief.md` — domain goal and open workplans (offline-safe)
2. Check inbox: `GET /messages/?to_agent=binky-control&unread_only=true`; mark read
3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks
4. Check human-needed tasks: `GET /tasks/?needs_human=true`
**During work:**
- Update task statuses in workplan files as tasks progress
- Record significant decisions via `POST /decisions/`
**Close:**
1. Update workplan file task statuses to reflect progress
2. Log: `POST /progress/` with a summary of what changed
3. After workplan file changes, run:
```bash
statehub fix-consistency
```
Coding agents should run this directly; ask the operator only if the CLI or
State Hub API is unavailable. This syncs task status from files into the hub DB.
---
{CREDENTIAL_ROUTING}
<!-- REPO-AGENTS-EXTENSIONS -->
<!-- Append repo-specific agent instructions below this marker.
The state-hub template sync preserves content after this line. -->
---
## Workplan Convention (ADR-001)
Work items originate as files in this repo — not in the hub. The hub is a
read/cache/index layer that rebuilds from files.
**File location:** `workplans/BINKY-WP-NNNN-<slug>.md`
**Archived location:** finished workplans may move to
`workplans/archived/YYMMDD-BINKY-WP-NNNN-<slug>.md`. The `YYMMDD` prefix is
the completion/archive date; the frontmatter `id` does not change.
**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use
`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use
this only for low-risk work completed directly; create a normal workplan for
anything needing analysis, design, approval, dependencies, or multiple phases.
**Frontmatter:**
```yaml
---
id: BINKY-WP-NNNN
type: workplan
title: "..."
domain: infotech
repo: binky-control
status: proposed | ready | active | blocked | backlog | finished | archived
owner: codex
topic_slug: ...
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
state_hub_workstream_id: "<uuid>" # fix-consistency — do not edit (legacy field name; workplan UUID)
---
```
Use `proposed` for a new draft, `ready` after review against current repo
state, and `finished` after implementation. `stalled` and `needs_review` are
derived health labels, not frontmatter statuses.
**Terminology:** workplan is the fleet term; `workstream` appears only in legacy
API/MCP/frontmatter bridges until `STATE-WP-0069` retires them — see
`the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`.
**Task block format** (one per `##` section):
```
## Task Title
` ` `task
id: BINKY-WP-NNNN-T01
status: wait | todo | progress | done | cancel
priority: high | medium | low
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
` ` `
Task description text.
```
Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work.
To create a new workplan:
1. Write the file following the format above
2. Run `statehub fix-consistency` locally; ask the operator only if the CLI or
State Hub API is unavailable.

105
INTENT.md Normal file
View file

@ -0,0 +1,105 @@
# INTENT
> Status: **draft v0.1** — 2026-07-16. Owner: Bernd Worsch. To be revised as the company canon grows.
## Why this company exists
Binky Hedgehog GmbH (founded 2019, until now a dormant legal shell) becomes the
commercial operating company for an ecosystem of **operational knowledge
infrastructure**. Its long-term identity is **Operational Knowledge GmbH — "OK"**.
The thesis:
> Companies increasingly fail not because they lack tools, but because their
> operational knowledge is fragmented, implicit, ungoverned, and not executable.
> This company provides products and services that turn operational knowledge
> into structured, governed, agent-ready company capabilities.
## What the company does
The company is the **economic crystallization point** of the ecosystem — it is
not the ecosystem itself.
- **Package** capabilities from the ecosystem into offers.
- **Sell and deliver** those offers to earn revenue.
- **Operate itself** on the same capabilities (dogfooding), turning every
internal operational pain into product evidence.
- **Feed learning back** into the ecosystem so capabilities mature.
The ecosystem pillars and their roles:
| Pillar | Role |
| --- | --- |
| **Coulomb** | Discover, cluster, mature, and package reusable capabilities |
| **Net Kingdom** | Identity, access, security, governance — make capability governable |
| **Railiance** | Reliable coordination and delivery — turn intentions into fulfilled commitments |
## The core loop: the OK Flywheel
1. An internal operational problem appears.
2. The company solves it with an ecosystem capability.
3. The solution is documented and instrumented.
4. The capability becomes reusable.
5. The reusable capability becomes a product or service.
6. Customer usage creates feedback.
7. Feedback improves the ecosystem.
8. The improved ecosystem improves company operations.
## How the company is operated
The company runs as a **human-on-the-loop, unattended-progress stack**: a solo
founder with ~1–3 hours per day outside business hours and roughly two
office-hour days per month.
Operating rules that follow from this:
- **"Ask Bernd" is never the default.** Agents continue with the safest useful
next step; uncertainty triggers research, comparison, or preparation — never
idle waiting.
- Work is classified into **autonomy lanes** (Green/Blue/Yellow/Orange/Red,
defined in `AutonomyPolicy.md`). Green and Blue work proceeds unattended;
Yellow becomes prepared decision packages; Orange batches to office-hour
days; Red stays human-only.
- Founder attention is the scarcest resource and is **budgeted explicitly**:
concise briefs, evidence-backed decision cards, approve/reject options.
- Valid system states are *proceeding*, *prepared for review*, or *deferred by
policy* — never *waiting because unsure*.
## What must remain human
Signing, strategic commitments, bank and payment execution, contracts,
sensitive legal/HR/security decisions, external commitments of the company,
risk acceptance, and final authority on direction. Agents prepare; the founder
decides.
## What counts as success
The success ladder (detail in `SuccessMilestones.md`):
```text
S1 company administratively clean
S3 first internal dogfood loop works
S5 first paid revenue
S6 repeatable productized service
S9 rename to Operational Knowledge GmbH makes sense
S12 acquiring ok.com becomes a rational decision
```
The rename to Operational Knowledge GmbH is a **milestone, not a starting
point** — it happens when the name clarifies the business more than it creates
friction (first repeatable offer, paying customer or serious pilot, coherent
messaging, dogfood evidence).
## Near-term aim
Make Binky Hedgehog GmbH practically operable and strategically aimed at
becoming Operational Knowledge GmbH: reactivate the legal/administrative
shell, map the ecosystem, form first offers (services before software), and
run the company on its own primitive control plane — this repo.
## This repo
`binky-control` is the company brain: the canon (intent, policies, plans),
the queues (decisions, office-hour, autopilot work), and the registries that
let agents and the founder share situational awareness with executable next
steps. Sister repo: `unattended-progress-company`.

37
SCOPE.md Normal file
View file

@ -0,0 +1,37 @@
# SCOPE
> This file was generated by `statehub register`. Refine it as the repository
> boundaries become clearer.
## One-liner
binky-control is the company control plane ("company brain") for Binky Hedgehog GmbH's transformation into Operational Knowledge GmbH, holding the canon (intent, policies, plans), work queues, and registries that give agents and the solo founder shared situational awareness with executable next steps.
## Core Idea
binky-control exists to provide the capability described in INTENT.md.
## In Scope
- Company canon: intent, policies (autonomy lanes), success milestones
- Queues for decisions, office-hour batches, and autopilot work
- Registries for founder/agent shared situational awareness
- Operating the human-on-the-loop, unattended-progress stack
- Dogfooding ecosystem capabilities on company operations
## Out of Scope
- Building the ecosystem pillars themselves (Coulomb, Net Kingdom, Railiance)
- Product/service source code and delivery artifacts
- Human-only actions: signing, contracts, payments, legal/HR/security decisions
- Sister-repo concerns tracked in unattended-progress-company
## Current State
- Early draft stage: single initial commit, INTENT.md at draft v0.1 (2026-07-16), referenced policy/milestone docs not yet present in the repo.
## Getting Oriented
- Start with: INTENT.md
- Agent instructions: AGENTS.md
- Workplans: workplans/

2238
history/260715-InitialExploration.md Normal file
View file

File diff suppressed because it is too large Load diff

55
workplans/BINKY-WP-0001-statehub-bootstrap.md Normal file
View file

@ -0,0 +1,55 @@
---
id: BINKY-WP-0001
type: workplan
title: "Bootstrap State Hub integration"
domain: infotech
repo: binky-control
status: ready
owner: codex
topic_slug: custodian
created: "2026-07-16"
updated: "2026-07-16"
---
# Bootstrap State Hub integration
binky-control is the company control plane ("company brain") for Binky Hedgehog GmbH's transformation into Operational Knowledge GmbH, holding the canon (intent, policies, plans), work queues, and registries that give agents and the solo founder shared situational awareness with executable next steps.
## Review Generated Integration Files
```task
id: BINKY-WP-0001-T01
status: todo
priority: high
```
Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`.
Replace generated placeholders with repo-specific facts where needed.
## Verify Local Developer Workflow
```task
id: BINKY-WP-0001-T02
status: todo
priority: high
```
Identify the repo's install, test, lint, build, and run commands. Add or refine
those commands in the agent instructions so future coding sessions can verify
changes confidently.
## Seed First Real Workplan
```task
id: BINKY-WP-0001-T03
status: todo
priority: medium
```
Create the first implementation workplan for the repository's most important
next change. After workplan file updates, run the sync locally from this repo
checkout:
```bash
statehub fix-consistency
```