docs(prompts): define organisation automation handoff

This commit is contained in:
sam committed 2026-10-17 02:25:32 +11:00
1 parent 41cd938748
commit 139338cf34
6 files changed
+378

No files matched your search

@@ -0,0 +1,69 @@
# Handoff: organisation-owned automation
Read this file and `GUIDELINES.md` before running a numbered implementation prompt.
The maintainer approved the architecture below. Implement it; do not restart a
navigation brainstorming exercise. The initial Antigravity navigation proposal
was rejected. A later externally authored design or Bead design field is not
additional approval.
## Approved product model
| Scope | Ownership |
| --- | --- |
| Account | Login methods, personal API tokens, preferences |
| Instance | Authentication providers, execution infrastructure, installed extensions, secret-engine infrastructure, organisation limits |
| Organisation | Members, execution identities, external connections, model configuration, workflows, schedules, channels |
| Workspace | Groups organisation work and resources; initially inherits organisation permissions |
| Task/run | Requesting actor, execution identity, resolved workflow and resource references |
External connections are explicit organisation resources. A forge connection
identifies its host, authentication reference and verified external account.
Repositories reference connections. Execution identities receive permission for
specified operations on those resources. Git commit authorship is separate from
authentication. Database-backed execution identities are authoritative.
Preserve existing service boundaries: State Store/control plane persists resources
and authority; archied resolves execution resources, performs Git operations and
verifies repository access; Gateway owns conversations and organisation-scoped
model use; UI presents contracts and diagnostics. Use existing gRPC contracts for
service communication. Do not add a service or access another service's tables.
A saved change must become effective without a server login. Connection state
must distinguish saved, applied, verified and failed. A resolved secret is not
proof of repository access. Setup follows the requested capability: repositories,
chat channels and a global default model are not universal prerequisites.
## Starting state to verify
The last implementation commit recorded at handoff was `57456b3e`, containing
independent settings/workflow/task diagnostic fixes. Architecture implementation
has not begun. No application source was edited in the architecture approval
session. Verify current history, checkout and working tree rather than assuming
that snapshot is current. Other agents may have worked since this handoff.
## Execution sequence
1. `01-execution-identities.md` — `archie-core-kgxw.13`.
2. `02-connections-and-repositories.md` — `archie-core-oygqd`.
3. `03-organisation-ownership.md` — `archie-core-3z4fd.8`.
4. `04-navigation-and-setup.md` — `archie-core-3z4fd.1`.
Beads is authoritative for progress and dependencies. The parent is
`archie-core-3z4fd`. These files are reusable instructions, not completion records.
Read each Bead before claiming it. Complete the current slice end to end before
starting the next. Do not close the parent until all acceptance criteria have
actual evidence. Do not delegate unless the maintainer explicitly authorises it.
## Final acceptance scenario
An organisation administrator configures a forge connection through the dashboard,
binds a private repository, permits an execution identity to clone/push/open a PR,
verifies access using the daemon, selects that identity in a workflow, and runs or
retries a task successfully. No configuration-file edit, restart, root credential
fallback or daemon secret in a container is needed. A separate repository-free
workflow runs without a forge connection. Cross-organisation use is refused.
Use an isolated authenticated private-repository equivalent for verification.
Production configuration, deployment, pushes and external posting require the
maintainer's explicit instruction. Do not use a dummy public/nonexistent
repository's failure as evidence for private-repository authentication.
@@ -0,0 +1,66 @@
# Implement live database execution identities
Read `00-start-here.md` and `GUIDELINES.md`. Work against
`archie-core-kgxw.13`; read and claim it before editing.
## Outcome
A bot or service account created and assigned through the dashboard can execute a
repository-free workflow without a configuration-file entry or process restart.
The database is the lifecycle and identity authority. A database identity cannot
silently acquire the root forge account, model authority or container grants.
## Source investigation
Trace `internal/domain/identity`, organisation agent assignment, State Store
identity RPC and principal assembly, `internal/app/archied/bootstrap.go`,
`internal/app/archied/main.go`, `internal/daemon/workflow_identity.go`,
`internal/daemon/workflow_org.go`, and identity-dependent paths in daemon.go and
kit_task.go. Inspect `ui/src/workflows/WorkflowSettings.vue` and the organisation
agent screen. Inspect every caller of declaredIdentity, identityMayAct,
identityFor, publisherIdentity, configFor, forgeFor, treesFor and repoFor.
At handoff, the UI offered database IDs but execution used startup-built
IdentityRunner objects from cfg.Identities. Forge/worktree NATS registrations
were also startup-only. Verify these facts. Changing just the identity lookup
while keeping root fallback paths would create a credential exposure.
## Required behaviour
1. Resolve a workflow's execution reference to a durable active agent identity.
Canonical references use stable IDs, independent of editable display names.
Refuse human, suspended, retired, missing and unassigned identities.
2. Establish the identity's organisation from authoritative assignment. Refuse
cross-organisation use even when a caller knows the other identity ID. Retain
checks for both workflow invocation and execution, including binding context.
3. Keep the persisted requesting actor distinct from the executing principal.
Check the record and worker handoff, not just in-memory task mutation.
4. New dashboard identities work live. Lifecycle or assignment changes affect
subsequent attempts. An unavailable identity authority causes an explicit
local refusal/dependency error, not permissive fallback.
5. Audit all resource and RPC resolution. Database agents must not inherit root
forge tokens, repository permissions or container credential grants. Do not
create a second cached identity authority to patch over the split.
6. Preserve existing configured identities through a narrowly scoped migration
into their actual owning organisation. Do not delete settings or silently
assign every identity to the system organisation. Preserve effective grants
without granting anything to newly created agents by default.
7. Keep repository authentication separate. A repository-free agent needs no
forge connection. Until the connection slice is implemented, reject unsupported
repository access explicitly rather than borrowing root credentials.
8. Make workflow identity selection use eligible identities of the active
organisation and display their names while saving stable IDs. Show loading,
unavailable and empty states truthfully.
Do not invent new meanings for `root` or replace it with another organisation's
agent automatically. Migrate existing references only with a deterministic,
organisation-correct mapping; surface genuinely ambiguous records for resolution.
## Acceptance evidence
Show a dashboard-created agent running a repository-free workflow through the
actual daemon path. Cover refused human, inactive, unassigned and cross-org
identities; authority outages; retry rechecks; and absence of root credential
inheritance. Verify a renamed agent still resolves by ID. Verify existing mapped
identities retain their permissions. Run the project gate and record evidence
and any remaining limitations in the Bead before closing it.
@@ -0,0 +1,68 @@
# Implement organisation forge connections and repository access
Read `00-start-here.md` and `GUIDELINES.md`. Work against
`archie-core-oygqd`. Its prerequisite is `archie-core-kgxw.13`; verify acceptance
before claiming this slice. Do not treat a closed issue without evidence as proof.
## Outcome and resource relationships
An organisation owns a named external connection. It identifies the forge host,
authentication reference and verified external account. A repository references
that connection. An execution identity is authorised for specified operations
such as clone, push and opening a PR. Commit author name/email remain independent
of the authenticating external account. Choose the smallest representation that
fits the existing control-plane resource and policy contracts; do not build a
new integration service or expose root config fields as the domain model.
## Investigate first
Trace existing control-plane resource registration and organisation validation,
repository policies, SecretRef handling, forge extensions and resolveForge in
archied, worktree.Manager authentication, task-scoped forge/worktree RPC authority,
apply-status reporting and settings API authorisation. Check every Git and forge
consumer, including intake polling, review handling, retries and post-run actions.
A secret-reference check currently performed by another service is not evidence
that archied can resolve and use that reference.
## Required behaviour
1. Organisation administrators manage connections and repository bindings through
API/dashboard with server-side authorisation. Other organisations cannot read,
modify, select, verify or execute against them by guessing an ID.
2. Reuse secret references and installed forge capabilities. Do not hardcode a
closed GitHub/Gitea list if enabled extensions already supply discovery.
Never return token values to the browser. Any credential-entry path must have
a real secure storage consumer, not store plaintext in generic config/audit.
3. Authorise operations for the actual execution identity and selected resource.
A valid token does not itself grant an agent permission. Do not grant blanket
write/issue/PR permissions when only clone/read is requested.
4. Resolve the selected connection in archied for the actual repository operation.
Apply updates live. Saved revision, applied revision and verified access are
distinct; failed changes must not falsely report that the new revision runs.
5. Test access through the daemon's real forge/Git path for the selected repository
and base branch, under the relevant execution identity's permissions. Report
which operation was checked. Read success cannot prove push or PR permission.
Verification must not create commits, branches or PRs as an incidental probe.
6. Credential rotation reaches subsequent operations without process restart.
Revoked permissions are enforced on subsequent operations/attempts. Avoid
stale cached credentials silently surviving changes.
7. Produce structured failures with a cause, affected resource/operation and an
authorised recovery action. Distinguish missing configuration, unavailable
secret/extension, denied authority and remote authentication/access failure.
A remote 401 or 'Repository not found' does not prove which underlying cause
occurred. Do not implement frontend substring/regex diagnosis.
8. Populate task repository choices from authorised configured repositories, not
only prior tasks. A failed task can lead to its connection and return to retry.
9. Migrate existing forge/repository configuration to its existing owner without
widening grants; remove obsolete runtime paths after all consumers migrate.
Do not force connection setup for repository-free workflows.
## Acceptance evidence
Use an isolated authenticated private-repository equivalent. Demonstrate dashboard
configuration, actual daemon clone, permitted push/PR execution where the test
workflow calls for it, credential rotation and refused unauthorised operations.
Show that another org and an ungranted agent cannot use the same connection.
Inspect worker handoff/logs to confirm tokens do not leak. Run a repository-free
workflow independently. Record exact limitations; no production configuration or
external posting is authorised by this prompt.
@@ -0,0 +1,54 @@
# Migrate automation resources to organisation ownership
Read `00-start-here.md` and `GUIDELINES.md`. Work against
`archie-core-3z4fd.8`. Read prior identity/connection changes before deciding what
remains; do not duplicate their resources or migrations.
## Outcome
Every automation resource resolves within its owning organisation and every
instance resource remains an explicitly administered infrastructure capability.
Existing settings retain their values, ownership and effective access.
## Required scope
Inspect the control plane's instanceOnlyKinds, runtime layering, org model
policy, provider/model selection, workflow definitions/enablement, schedules,
channel settings, event sources/bindings, execution profiles and task/container
policies. Inspect all runtime consumers and authorization paths before changing
scope. Use the ownership table in `00-start-here.md` as the approved target.
Do not mechanically remove kinds from instanceOnlyKinds and declare completion.
## Rules and implementation requirements
1. Resolve organisational resources from the task/request's authoritative org
context. Do not trust a submitted org field, retain a root context by accident,
or query a different service's tables.
2. Preserve the distinction between installed instance capability, organisation
configuration and organisation permission to use shared infrastructure.
Existing org model policy must remain effective. Instance infrastructure
limits remain enforceable even when organisations configure automation.
3. Keep workspace semantics narrow: group organisation work/resources and inherit
organisation permission initially. Do not invent a second workspace policy
system or weaken existing explicit restrictions.
4. Establish deterministic ownership for existing records before migration.
Preserve valid instance defaults only where the model explicitly allows
inherited infrastructure defaults. Do not copy secrets or permissions into
every tenant. Ambiguous ownership must be visible, never guessed.
5. Make migrations safe to resume and maintain atomicity where records must agree.
An interrupted migration must not silently lose settings or broaden access.
Regenerate affected contracts and update every reader/writer/fixture.
6. Saved org settings need functioning runtime consumers, apply status and
dependency failure handling. Watches/caches must be keyed by organisation as
well as resource/revision wherever shared processes consume multiple tenants.
7. Remove superseded global paths after callers and data move. Do not maintain
two independent sources of truth. Preserve accepted work while peers restart.
## Acceptance evidence
Demonstrate two organisations with distinct effective resources using actual
service/API paths. Verify configuration changes and restarts retain separation,
and that requests/tasks cannot read or use another org's configuration. Verify
migration of representative existing configuration without widened permissions,
including interrupted/repeated migration semantics where applicable. Follow
AGENTS.md for SQL/security regression tests and run the final project gate.
@@ -0,0 +1,54 @@
# Implement navigation and contextual setup from working contracts
Read `00-start-here.md` and `GUIDELINES.md`. Work against
`archie-core-3z4fd.1`. Verify its connection and ownership prerequisites before
starting. The old page-rearrangement proposal is rejected, not a UI specification.
## Outcome
The visible application reflects actual resource ownership. An operator can find
and complete the setup needed for a particular workflow and recover a failed run
without guessing which settings page owns the problem.
## Required behaviour
1. An organisation selector establishes context. Workflows, Tasks, Connections
and Organisation settings operate in that context. Switching org must clear
or refetch scoped state and prevent stale responses from contaminating it.
2. Instance administration is a separate administrator destination for
infrastructure and instance limits. Personal login security, API tokens and
preferences live in the account menu. Do not recreate a catch-all Access page.
3. Connections are discoverable organisation resources. A repository opens its
connection; a workflow shows the execution identity/resources it needs; a
failed task links to an authorised recovery action. Show names with stable
references, without duplicate organisation labels or unexplained internal IDs.
4. Setup is contextual. A repo-required workflow offers missing connection,
repository, identity or model configuration where needed. A repository-free
workflow never demands GitHub. Chat channels and a global default model are
not universal setup prerequisites. Do not add a mandatory global wizard.
5. Readiness comes from backend capability diagnostics for the selected org,
identity, workflow and resource. Distinguish saved/applied/verified/failed.
Do not infer readiness from nonempty fields, task counts or a resolved secret.
6. Recovery consumes structured service errors. The browser must not classify
root causes using error-string patterns or display actions the user cannot
perform. Preserve task context when moving to configuration and returning.
7. Preserve the prior working settings draft/save flow, readable width, review
diffs, workflow validation and truthful loading/error states. Do not reintroduce
native navigation prompts that discard drafts or collisions with the chat FAB.
8. Keep technical implementation details out of normal product copy. Explain
connection/account/permission problems in terms useful to the operator, not
daemon config keys, NATS subjects or secret plumbing.
## Acceptance evidence
Drive the real local UI: create or select an org, configure the private-repository
connection, choose a valid execution identity, verify repository access, start a
workflow, encounter and recover a controlled access failure, then retry. Also run
repository-free automation without forge setup. Verify a second org cannot see
or select the first org's resources, including after switching org during an
in-flight fetch. Check administrator, ordinary member and personal account views,
loading/error states, keyboard access and a narrow viewport. Capture evidence,
regenerate embedded UI output and run the exact final tree's project gate.
Do not claim a successful user journey based solely on mocked screenshots or
fixture state. Leave unmet criteria explicitly open in Beads.
@@ -0,0 +1,67 @@
# Mandatory execution guidelines
These rules apply to every numbered prompt. Read the current root and scoped
AGENTS.md files first; the maintainer's current instructions take precedence.
## Before edits
- Verify the requested checkout, branch, working tree and other active writers.
Preserve unrelated changes. Do not reset, stash or overwrite another agent.
- Read and claim the named Bead. Create any missing issue before starting its
work. Record implementation discoveries and remaining work in Beads, never a
second Markdown task ledger. Do not sync Beads externally unless told.
- Trace the complete affected path: UI, API, service contract, authorisation,
persistence, runtime consumer, retries, fixtures and generated artifacts.
- Name the smallest complete change. Reuse existing resource, secret-reference,
authorisation, apply-status and service-contract mechanisms. If a new mechanism
or a change exceeding roughly 100 lines is needed, assess simpler alternatives
and record why they fail. This assessment does not mean asking again for an
already approved direction.
- Treat file names and line references in these prompts as investigation leads.
Verify the current source; do not implement from stale notes alone.
## Implementation boundaries
- Preserve service isolation, durable acknowledgement and local failure. An
unavailable peer must not terminate unrelated services or discard accepted work.
- Enforce organisation ownership and operation permissions on the server. Hidden
UI controls are not an authorisation boundary. Caller-supplied organisation or
identity values are not trusted facts.
- Keep requesting actor, execution principal, external account and commit author
distinct. Never infer authority from a display name or a matching account name.
- Never fall back to root credentials or broad grants when resolution fails.
Never grant every existing organisation access to migrated global resources.
- The model never runs Git. Daemon credentials never enter agent containers,
task briefs, browser responses or logs. Task-scoped grants expire/revoke when
execution ends. Task briefs remain under `.git/task.json`.
- Persist settings through the control plane and implement their runtime consumer
in the same slice. Do not ship parse-only fields, decorative readiness badges,
restart instructions or a server-login workaround as completion.
- Remove obsolete paths only after migrating their data and callers. No parallel
identity authority, duplicated ownership model or indefinite compatibility shim.
- No new service, binary, generic framework, broad cleanup or speculative feature.
File unrelated discoveries as Beads instead of fixing them in passing.
## Verification and delivery
- For a reported bug, reproduce it with a meaningful failing regression before
fixing it. Cover changed security, workflow and SQL semantics as required by
AGENTS.md. Do not add tests of constants, wiring or struct shapes.
- Verify through real API/runtime/browser paths when the acceptance requires
them. State Store fixtures and mocks must be labelled; they do not prove actual
private Git access, credential rotation or successful agent execution.
- Do not open a real database or require Docker in unit tests. Use the isolated
integration/e2e environment for real service verification.
- Follow current project instructions for framework/library documentation. Never
send secrets, production identifiers or credential contents to documentation tools.
- Regenerate protobuf and embedded UI assets when their sources change; do not
hand-edit generated output. Run appropriate targeted checks, then `task check`
on the exact final tree before committing. Never run concurrent full gates.
- Stage only your own paths, never `.beads/`, binaries or scratch output. Commit
finished work with a short scoped Conventional Commit. Do not push or deploy.
- Close a Bead only when its stated acceptance is demonstrated. If something
remains unverified, record exactly what and why; leave the issue open. Never
describe a partial implementation as end-to-end completion.
- Report what changed, what was verified and the material remaining limitation.
Keep useful progress updates concise. Ask only for unresolved product decisions
or explicitly restricted external/destructive actions.