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

docs: define agent workforce execution boundary
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 2s
Details

Browse source
This commit is contained in:
tegwick 2026-08-21 00:21:53 +02:00
parent c51163bff7
commit a09ad2e4ae
3 changed files with 310 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

180
SCOPE.md
View file

@ -1,32 +1,186 @@
# SCOPE # SCOPE
> This file was generated by `statehub register`. Refine it as the repository > Reviewed 2026-08-20 against the implemented Helix Forge loop and the
> boundaries become clearer. > cross-repository leadership/workforce architecture discussion. For the
> stable purpose and desired organizational outcome, see `INTENT.md`.
## One-liner ## One-liner
Iterating towards optimal agentic performance. Agent-workforce performance and lifecycle management: learn from agent
execution, improve the fleet, and—once the proposed contracts are
implemented—plan and govern which agents fill which roles within
leadership-owned goals and delegated resource envelopes.
## Core Idea ## Core Idea
agentic-resources exists to provide the capability described in INTENT.md. `agentic-resources` treats AI agents as a managed digital workforce rather
than as isolated prompts or interchangeable runtime processes.
## In Scope Its implemented Helix Forge subsystem captures coding sessions, finds
repeated friction and successful techniques, curates and distributes reviewed
solution patterns, measures their effectiveness, and produces fleet
retrospectives. This is already the performance-and-development loop described
by `INTENT.md`.
- Maintain the repository's primary implementation. The recommended next boundary extends that evidence base into agent inventory,
- Keep docs, tests, and operational metadata current. selection, assignment, capacity planning, development, portfolio review,
rebalancing, and retirement. This repository may translate authorized goals
and constraints into a workforce plan, but it does not create organizational
strategy, leadership authority, money, technical capacity, or execution
permissions.
## Current Implemented Scope
- Capture and normalize Claude, Codex, and Grok coding sessions.
- Retain session digests and raw evidence within explicit storage budgets.
- Detect recurring failure, friction, cost, and success signals across the
fleet.
- Curate evidence-backed solution patterns through a review and approval flow.
- Render approved patterns as agent-flavor-specific, reviewable distribution
proposals.
- Measure before/after pattern effectiveness and fleet trends.
- Publish weekly retrospectives and correlate fleet-level Helix Forge evidence
with project-level KaizenAgentic metrics by reference.
## Recommended Workforce-Management Boundary
The following concerns fit the intent and existing performance subsystem, but
their contracts and implementation do not yet exist in this repository:
- Maintain an inventory of available agent capabilities, instances, status,
lifecycle stage, and evidence of fitness.
- Own the `RoleAssignment` control contract: which agent instance fills which
part of a role for which goals, under which leadership mandate and resource
envelope.
- Express execution needs through a versioned `glas-harness` profile reference
or compatible requirements contract, rather than coupling assignments to one
concrete rein or base model.
- Match agents, role duties, and Kaizen blueprints using explicit suitability
evidence; record unstaffed or deliberately human-owned duties.
- Allocate concurrent agent and duty capacity within authoritative financial,
technical-resource, token, time, and human-attention constraints.
- Aggregate outcomes, costs, refusals, and escalation quality by goal, role,
assignment, and duty.
- Maintain performance and development plans and recommend continue, coach,
refine, reallocate, pause, or retire decisions.
- Run portfolio reviews and propose rebalancing while requiring the authorized
leadership source to approve goal reprioritization, material envelope
changes, or wider authority.
Consumer-owned assignment/instance manifests should remain the durable source
initially; this repository can validate, index, plan, and review them without
prematurely requiring a central workforce service.
## Leadership and Workforce Relationship
Leadership and workforce management are adjacent control layers, not synonyms:
```text
organization intent
-> leadership-owned StrategicGoal + LeadershipMandate
-> delegated ResourceEnvelope
-> agentic-resources workforce plan + RoleAssignment
-> Kaizen blueprint + consumer-owned AgentInstance
-> activity-core scheduled work
-> glas-harness profile resolution
-> selected rein + base-model + sandbox constellation
-> outcome, cost, evidence, refusal, escalation
-> leadership review + workforce rebalance + blueprint improvement
```
- A `StrategicGoal` states the desired outcome, priority, horizon, and success
measures. Its authoritative source is the accountable organization or
engagement control plane.
- A `LeadershipMandate` states who may decompose goals, direct work, make which
decisions, delegate, pause, and escalate. A role title or agent prompt never
creates this authority.
- A `ResourceEnvelope` composes provenance-bearing limits from leadership,
`fin-hub`, `resource-control`, and runtime policy. Unknown capacity or budget
is never treated as unlimited.
- A `RoleAssignment` is the workforce decision within those inputs. It binds a
specific agent instance to selected role duties and records evidence,
limits, lifecycle, and review state.
Agentic-resources therefore advises and administers the agent workforce;
leadership remains accountable for direction, priority, material commitments,
and expansion of authority.
## Ecosystem Boundaries
| Concern | Owning source | Relationship to agentic-resources |
|---|---|---|
| Organizational intent, goals, priorities, and leadership mandates | Contextual organization/engagement control source; for example `binky-control` for Binky Hedgehog GmbH | Consume stable references; return portfolio evidence and recommendations; never invent or silently reprioritize strategy |
| Organizational role definitions | `role-engine` | Consume pinned role revisions and duty/authority boundaries; do not redefine roles or grant permissions |
| Agent blueprints, protocols, and project metrics | `kaizen-agentic` | Consume versioned blueprints and run evidence; supply assignment and performance context |
| Agent workforce inventory, assignment, capacity, development, and portfolio review | `agentic-resources` (recommended boundary; not yet implemented beyond performance learning) | Own the workforce plan and assignment lifecycle |
| Human workforce lifecycle and mixed-team concerns | `human-resources` | Share compatible vocabulary and handoff contracts; keep human-sensitive, employment, welfare, and compensation records separate |
| Monetary budgets, commitments, burn, runway, and AI-plan booked cost | `fin-hub` | Consume authoritative constraint signals and publish attribution; do not copy the financial ledger or approve spending |
| Resource identity, demand, capacity, utilization, allocation evidence, and technical economics | `resource-control` | Consume planning/evidence signals; do not procure, operate, or invent capacity |
| Scheduling and durable claimable work | `activity-core` | Supply active assignment/duty context; do not own the clock, queue, retry, or task lifecycle |
| Harness contract, execution profiles, backend routing, sandbox coordination, and gateway evidence | `glas-harness` | Supply an approved, versioned profile or execution requirements; let Glas resolve the concrete rein and sandbox constellation; consume its unified result evidence |
| Concrete inner agentic loop and backend-specific credentials/policy | Selected rein under `glas-harness`; currently including `rein-aharness` and `rein-openweights` | Treat a rein as a replaceable execution backend, not the workforce architecture boundary; `rein-aharness` is the live Claude-Code-CLI rein, not the meta-framework |
| Identity, credentials, and authorization | Identity, OpenBao/credential-routing, and policy systems | Reference routes and policy profiles only; never store secrets or treat organizational wording as technical access |
| Base-model/provider execution and inference routing | `llm-connect`, the selected rein, and provider adapters under their declared boundaries | Select through the approved Glas execution profile/route; consume usage/outcome evidence; do not hard-code a vendor model into workforce records or become a model gateway |
| Durable coordination read model | Custodian State Hub | Publish/index work and evidence; do not replace source files or hub ownership |
## Out of Scope ## Out of Scope
- Own unrelated adjacent systems. - Setting organizational strategy, goals, or cross-goal priorities.
- Make irreversible operational decisions without human approval. - Granting leadership mandates, technical authorization, credentials, or tool
permissions.
- Owning human personnel records, hiring, compensation, employment decisions,
welfare, or human performance surveillance.
- Owning the canonical role catalog or treating a role definition as a live
assignment.
- Owning monetary budget truth, payment/commitment approval, procurement,
infrastructure inventory, or provider capacity.
- Owning schedules, queues, workflow/task lifecycle, LLM sessions, or runtime
policy enforcement.
- Selecting a concrete rein or base model outside the approved
`glas-harness` profile/route, or treating `rein-aharness` as the universal
execution architecture.
- Automatically applying self-modifications or retiring live agents without
the review and authority required by the relevant mandate.
- Replacing KaizenAgentic, role-engine, activity-core, `glas-harness`, its
concrete reins, State Hub, fin-hub, or resource-control with a monolithic
agent-management service.
## Intent Relationship
`INTENT.md` describes the desired organizational outcome: a trustworthy,
antifragile agent ecosystem that improves performance and augments human
ingenuity through lifecycle management, oversight, and continuous alignment.
It is deliberately broader than this repository's implementation ownership.
This scope realizes that intent through a federated operating model. The repo
owns the agent-workforce performance and lifecycle concern while consuming
strategy, role, budget, resource, policy, runtime, and human-workforce facts
from their authoritative systems.
## Current State ## Current State
- Status: active; implementation and stability should be verified by the repo agent. - **Implemented:** the Helix Forge capture -> detect -> curate -> distribute ->
measure loop, weekly retrospectives, and Kaizen metrics correlation.
- **Completed work:** `AGENTIC-WP-0001` through `AGENTIC-WP-0011`; there are no
active normal workplans at the time of this review.
- **Architecture proposal:** accept agentic-resources as the workforce and
assignment owner, subject to cross-repository ratification.
- **Execution-layer implementation:** `GLAS-WP-0004` now provides strict
versioned requests/profiles, deterministic rein-registry validation,
explicit CLI/gateway selection, and one normalized evidence envelope.
`rein-aharness` is one current backend; workforce contracts preserve freedom
to choose a different rein, sandbox, tool policy, and base-model
constellation by changing the approved Glas profile reference. The
Claude-backed and open-weight profiles both have live success, real-commit,
and sandbox-cleanup evidence through the same Glas contract.
- **Implementation gap:** agent inventory, `RoleAssignment`, capacity
allocation, goal/resource-envelope correlation, development plans, and
portfolio/retirement workflows are not implemented yet.
## Getting Oriented ## Getting Oriented
- Start with: INTENT.md 1. `INTENT.md` — stable organizational purpose.
- Agent instructions: AGENTS.md 2. `docs/PRD-helix-forge.md` — implemented product boundary and architecture.
- Workplans: workplans/ 3. `session_memory/README.md` — current operational capabilities.
4. `docs/DESIGN-session-memory.md` — detailed design and Kaizen correlation.
5. `workplans/` — implementation history and future work.

71
WORK-RECORDS.md Normal file
View file

@ -0,0 +1,71 @@
# Work Records — agentic-resources
> Generated by `statehub fix-consistency` (CUST-WP-0061-T04, work-record
> stage 3). Do not edit by hand — edit the source file/block listed for
> each record and re-run fix-consistency to refresh this index. Archived
> workplans are omitted; closed decisions/intakes/engagements stay listed
> so recently-resolved work is still visible. [auto]
| Kind | ID | Status | Lane | Source |
| --- | --- | --- | --- | --- |
| workplan | ADHOC-2026-08-20 | finished | — | workplans/ADHOC-2026-08-20.md |
| workplan | AGENTIC-WP-0001 | finished | — | workplans/AGENTIC-WP-0001-statehub-bootstrap.md |
| workplan | AGENTIC-WP-0002 | finished | — | workplans/AGENTIC-WP-0002-session-memory-phase0.md |
| workplan | AGENTIC-WP-0003 | finished | — | workplans/AGENTIC-WP-0003-session-memory-phase1.md |
| workplan | AGENTIC-WP-0004 | finished | — | workplans/AGENTIC-WP-0004-session-memory-phase2.md |
| workplan | AGENTIC-WP-0005 | finished | — | workplans/AGENTIC-WP-0005-detect-hardening.md |
| workplan | AGENTIC-WP-0006 | finished | — | workplans/AGENTIC-WP-0006-error-body-mining.md |
| workplan | AGENTIC-WP-0007 | finished | — | workplans/AGENTIC-WP-0007-session-memory-phase3.md |
| workplan | AGENTIC-WP-0008 | finished | — | workplans/AGENTIC-WP-0008-read-before-edit-reflex.md |
| workplan | AGENTIC-WP-0009 | finished | — | workplans/AGENTIC-WP-0009-session-memory-phase4.md |
| workplan | AGENTIC-WP-0010 | finished | — | workplans/AGENTIC-WP-0010-weekly-retro.md |
| workplan | AGENTIC-WP-0011 | finished | — | workplans/AGENTIC-WP-0011-kaizen-correlation-followup.md |
| task | ADHOC-2026-08-20-T01 | done | — | workplans/ADHOC-2026-08-20.md |
| task | ADHOC-2026-08-20-T02 | done | — | workplans/ADHOC-2026-08-20.md |
| task | AGENTIC-WP-0001-T01 | done | — | workplans/AGENTIC-WP-0001-statehub-bootstrap.md |
| task | AGENTIC-WP-0001-T02 | done | — | workplans/AGENTIC-WP-0001-statehub-bootstrap.md |
| task | AGENTIC-WP-0001-T03 | done | — | workplans/AGENTIC-WP-0001-statehub-bootstrap.md |
| task | AGENTIC-WP-0002-T01 | done | — | workplans/AGENTIC-WP-0002-session-memory-phase0.md |
| task | AGENTIC-WP-0002-T02 | done | — | workplans/AGENTIC-WP-0002-session-memory-phase0.md |
| task | AGENTIC-WP-0002-T03 | done | — | workplans/AGENTIC-WP-0002-session-memory-phase0.md |
| task | AGENTIC-WP-0002-T04 | done | — | workplans/AGENTIC-WP-0002-session-memory-phase0.md |
| task | AGENTIC-WP-0002-T05 | done | — | workplans/AGENTIC-WP-0002-session-memory-phase0.md |
| task | AGENTIC-WP-0002-T06 | done | — | workplans/AGENTIC-WP-0002-session-memory-phase0.md |
| task | AGENTIC-WP-0002-T07 | done | — | workplans/AGENTIC-WP-0002-session-memory-phase0.md |
| task | AGENTIC-WP-0003-T01 | done | — | workplans/AGENTIC-WP-0003-session-memory-phase1.md |
| task | AGENTIC-WP-0003-T02 | done | — | workplans/AGENTIC-WP-0003-session-memory-phase1.md |
| task | AGENTIC-WP-0003-T03 | done | — | workplans/AGENTIC-WP-0003-session-memory-phase1.md |
| task | AGENTIC-WP-0003-T04 | done | — | workplans/AGENTIC-WP-0003-session-memory-phase1.md |
| task | AGENTIC-WP-0003-T05 | done | — | workplans/AGENTIC-WP-0003-session-memory-phase1.md |
| task | AGENTIC-WP-0003-T06 | done | — | workplans/AGENTIC-WP-0003-session-memory-phase1.md |
| task | AGENTIC-WP-0003-T07 | done | — | workplans/AGENTIC-WP-0003-session-memory-phase1.md |
| task | AGENTIC-WP-0003-T08 | done | — | workplans/AGENTIC-WP-0003-session-memory-phase1.md |
| task | AGENTIC-WP-0004-T01 | done | — | workplans/AGENTIC-WP-0004-session-memory-phase2.md |
| task | AGENTIC-WP-0004-T02 | done | — | workplans/AGENTIC-WP-0004-session-memory-phase2.md |
| task | AGENTIC-WP-0004-T03 | done | — | workplans/AGENTIC-WP-0004-session-memory-phase2.md |
| task | AGENTIC-WP-0004-T04 | done | — | workplans/AGENTIC-WP-0004-session-memory-phase2.md |
| task | AGENTIC-WP-0004-T05 | done | — | workplans/AGENTIC-WP-0004-session-memory-phase2.md |
| task | AGENTIC-WP-0004-T06 | done | — | workplans/AGENTIC-WP-0004-session-memory-phase2.md |
| task | AGENTIC-WP-0004-T07 | done | — | workplans/AGENTIC-WP-0004-session-memory-phase2.md |
| task | AGENTIC-WP-0005-T01 | done | — | workplans/AGENTIC-WP-0005-detect-hardening.md |
| task | AGENTIC-WP-0005-T02 | done | — | workplans/AGENTIC-WP-0005-detect-hardening.md |
| task | AGENTIC-WP-0005-T03 | done | — | workplans/AGENTIC-WP-0005-detect-hardening.md |
| task | AGENTIC-WP-0006-T01 | done | — | workplans/AGENTIC-WP-0006-error-body-mining.md |
| task | AGENTIC-WP-0006-T02 | done | — | workplans/AGENTIC-WP-0006-error-body-mining.md |
| task | AGENTIC-WP-0006-T03 | done | — | workplans/AGENTIC-WP-0006-error-body-mining.md |
| task | AGENTIC-WP-0007-T01 | done | — | workplans/AGENTIC-WP-0007-session-memory-phase3.md |
| task | AGENTIC-WP-0007-T02 | done | — | workplans/AGENTIC-WP-0007-session-memory-phase3.md |
| task | AGENTIC-WP-0007-T03 | done | — | workplans/AGENTIC-WP-0007-session-memory-phase3.md |
| task | AGENTIC-WP-0007-T04 | done | — | workplans/AGENTIC-WP-0007-session-memory-phase3.md |
| task | AGENTIC-WP-0007-T05 | done | — | workplans/AGENTIC-WP-0007-session-memory-phase3.md |
| task | AGENTIC-WP-0008-T01 | done | — | workplans/AGENTIC-WP-0008-read-before-edit-reflex.md |
| task | AGENTIC-WP-0008-T02 | done | — | workplans/AGENTIC-WP-0008-read-before-edit-reflex.md |
| task | AGENTIC-WP-0009-T01 | done | — | workplans/AGENTIC-WP-0009-session-memory-phase4.md |
| task | AGENTIC-WP-0009-T02 | done | — | workplans/AGENTIC-WP-0009-session-memory-phase4.md |
| task | AGENTIC-WP-0009-T03 | done | — | workplans/AGENTIC-WP-0009-session-memory-phase4.md |
| task | AGENTIC-WP-0010-T01 | done | — | workplans/AGENTIC-WP-0010-weekly-retro.md |
| task | AGENTIC-WP-0010-T02 | done | — | workplans/AGENTIC-WP-0010-weekly-retro.md |
| task | AGENTIC-WP-0010-T03 | done | — | workplans/AGENTIC-WP-0010-weekly-retro.md |
| task | AGENTIC-WP-0011-T01 | done | — | workplans/AGENTIC-WP-0011-kaizen-correlation-followup.md |
| task | AGENTIC-WP-0011-T02 | done | — | workplans/AGENTIC-WP-0011-kaizen-correlation-followup.md |
| task | AGENTIC-WP-0011-T03 | done | — | workplans/AGENTIC-WP-0011-kaizen-correlation-followup.md |

72
workplans/ADHOC-2026-08-20.md Normal file
View file

@ -0,0 +1,72 @@
---
id: ADHOC-2026-08-20
type: workplan
title: "Clarify agentic-resources scope for leadership and workforce architecture"
domain: infotech
repo: agentic-resources
status: finished
owner: codex
topic_slug: agent-workforce-governance
created: "2026-08-20"
updated: "2026-08-20"
---
# Clarify agentic-resources scope for leadership and workforce architecture
## Review and refine the repository boundary
```task
id: ADHOC-2026-08-20-T01
status: done
priority: medium
```
Review the implemented Helix Forge subsystem, `INTENT.md`, and the current
cross-repository architecture proposal from KAIZEN-WP-0013. Replace the stale
generated `SCOPE.md` with an evidence-based operational boundary that:
- distinguishes implemented agent-performance learning from proposed
workforce-management contracts;
- relates leadership-owned goals and mandates to agent workforce assignments;
- maps role, blueprint, budget, resource, scheduling, runtime, human-workforce,
and policy ownership without creating a monolithic control plane; and
- records the unimplemented inventory, `RoleAssignment`, capacity,
development, portfolio, and retirement gap.
Completed 2026-08-20. `SCOPE.md` now documents the current implementation, the
recommended agent-workforce boundary, the leadership-to-execution control
spine, explicit ecosystem ownership, and current maturity gaps.
## Correct the execution-layer abstraction
```task
id: ADHOC-2026-08-20-T02
status: done
priority: medium
```
Review `glas-harness` and `rein-aharness` implementation, intent, scope,
contracts, registry, and accepted ADRs. Correct the agentic-resources
architecture so the workforce and instance contracts target `glas-harness` as
the primary execution-layer abstraction rather than coupling directly to
`rein-aharness`.
Completed 2026-08-20. The scope now identifies Glas as owner of the harness
contract, execution profiles, rein routing, sandbox coordination, and gateway
evidence. Concrete reins—including the live Claude-Code-based
`rein-aharness` and the implemented `rein-openweights` alternative—remain
replaceable inner-loop backends. Assignment and instance contracts should
reference a versioned Glas profile or compatible execution requirements so
the rein, sandbox, tool policy, and base-model constellation can vary without
rewriting workforce architecture.
Follow-through later on 2026-08-20: `GLAS-WP-0004` implemented the referenced
contract as Glas contract `1.0`, including explicit versioned profiles for
`rein-aharness` and `rein-openweights`, common execution evidence, and
assignment/role/duty/goal/resource-envelope reference fields. The
agentic-resources boundary above is now an available execution integration,
not only an architectural target.
Live follow-through completed 2026-08-21: both the Claude-backed and
open-weight profiles completed the same bounded task with real commits and
verified sandbox teardown through the Glas contract.