Skip to content

Add a portable owner-agent entry for Factory - #92

Draft
gustavonline wants to merge 1 commit into
docs/foundation-host-coordination-83from
feat/owner-agent-entry-91
Draft

gustavonline wants to merge 1 commit into
docs/foundation-host-coordination-83from
feat/owner-agent-entry-91

Conversation

@gustavonline

Copy link
Copy Markdown
Contributor

An owner-side agent sent application work to Factory's method lead as though it were a general coordinator. This adds a portable factory-entry skill that routes requests to the right existing project lead and carries the candidate, authority and holds through follow-up and resume.

The existing stage helper can now produce all nine canonical skills as one fresh manifest-bound set. Foundation's setup and adoption guidance connects the owner's entry to host roles, deliberate native installation/discovery/use, and recovery. Portable skills are the selected route; plugin distribution remains an option.

Stacked on draft #85 at 088e0997; its accepted #83 source is unchanged. Source scope for #91 only. The issue stays open for real caller adoption and useful routing.

Validation: package check 9 skills / 0 errors; 16 unit tests passed; all-set staging 9 skills / 28 verified files. One fresh caller context generated the intended handoffs/decisions for six synthetic cases:

Case Observed source-method outcome
Method work Existing Factory method lead; owner retains delivery
Application continuation Existing application lead/writer; held migration does not stop independent keyboard work
Two projects Separate bounded research handoffs; imported runtime change grants no implementation
Stale or missing recipient Correct current project binding; missing route retained without a new lead or Factory fallback
Host resume Real uninstalled stage verified; account/role, wake, reboot and discovery limits retained
Changed delivery candidate Current head and pending human decision retained; prior decline and independent work preserved

Independent exact-candidate Sol 6.1 Max/default review: ACCEPT, no actionable findings. It independently reconstructed the 46-file tree, verified preservation of the PR #85 base, checked all staged resources/licenses and assessed the actual six-case artifacts.

Reviewed commit 477e6da1729a32ecc7a0af3ed424fa6bd63bc923, tree dd2a112711d0b9663d2e8805877e778746454bc3; only 11 source paths change. A final all-set stage from this clean commit records its exact Git revision and matches the exercised 28 payload bytes. The same Opus 5.5 High/Fast-off writer performed the source change; the preserved human author and actual Claude coauthor are verified in the commit. Nothing is installed into an active caller. Native discovery/use and host recovery are untested here; staging and fixtures establish neither. Human delivery under #88 and branch protection remains required; no merge or release is requested.

Refs #91, #83.

Route method, application and bounded cross-project requests to their existing
leads. Extend canonical staging with one all-skill set and connect native
discovery, role setup and resume guidance to Foundation.

Refs #91. Builds on the accepted #83 source in PR85.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@gustavonline

Copy link
Copy Markdown
Contributor Author

Reviewed operator handoff — PREPARED ONLY. The same Opus 5.5 High/Fast-off writer prepared this procedure and repaired one loading-evidence gap. A fresh independent Sol 6.1 Max/default delta review returned ACCEPT, with F1 resolved and no remaining material findings. This accepts the procedure, not installation or native capability.

The unchanged r3 document below is 15,455 UTF-8 bytes, SHA-256 fcadaf7bb38cc5d4209f48e741233f0ecec3e8dbdce3f5fd242cd292a30edef6. It binds the proposed operator steps to source 477e6da1729a32ecc7a0af3ed424fa6bd63bc923; no green source checks were repeated. The earlier procedure finding and actual review reports remain retained with qualification evidence. Official local skill documentation is documentation, not proof of the target caller's current discovery or loading.

Decision scope: human delivery of exact PR85/PR92 heads remains separate from any named owner-account/host/native-scope preview authorization for only factory-entry and complete factory-foundation. A preview can be authorized from this unmerged immutable candidate without granting merge/release or restart. Current authority is preparation only; no preview adoption decision is recorded here. #91 remains open. Installation, discovery/loading, real use/resume and recovery are NOT RUN.

The existing owner-side operator is the next holder. The text below can be consumed through this normal GitHub/native handoff; no Factory-host file access, new runtime, broad rights or application assignment is needed to read it.


Factory #91: adopting the owner entry in your own AI agent

This is a finite procedure for the owner's existing operator and everyday AI agent
(the caller). It installs two reviewed Factory skills into the caller's own skill
scope, checks that the caller actually finds and uses them, and leaves a clean way
back. Nothing in it has been run. Preparing it authorizes none of its effects; see
Authority before step 3.

The candidate

Fact Value
Repository https://github.com/arcitai/factory
Source commit 477e6da1729a32ecc7a0af3ed424fa6bd63bc923
Source tree dd2a112711d0b9663d2e8805877e778746454bc3
Version 0.1.20 candidate source; not a release
Pull requests Draft #92, stacked on draft #85 (head 088e09973728ceb02e8b9a04447860145c5c3bb5); neither is merged
Review and CI Independent Sol 6.1 Max/default review: ACCEPT, no actionable findings. Method checks passed on this exact head
Reviewed stage all set: 9 skills, 28 manifest-bound files, sourceRevision = the commit above, sourceModified = false, manifest SHA-256 885b264c0d2013f7e1565fc5b15755a0314ffbe352803b6ef5ba6ec739538aca

No new source change, package or check run is needed. Use only this commit; do not
follow a branch or tag that can move.

What gets installed

Only two complete skill folders from the staged set, each with its references and
LICENSE:

  • factory-entry: tells the caller where each Factory request belongs. It
    routes; it never becomes a lead.
  • factory-foundation: the setup method the entry loads when the owner asks
    about a host.

Existing project AgentOps and ADLC installations and threads stay as they are. The
caller may read those skills explicitly when needed, but it is not assigned any
project's lead role.

Proposed destination: the owner's own Codex user skill directory,
~/.agents/skills, as resolved in the owner's own account. It is shared across
that owner's projects. It is not the Factory execution account, CODEX_HOME, a
cache, a plugin registry or a personal connector. Use the owner's project scope
(.agents/skills in one repository) instead only if the owner explicitly chooses
it and the caller's actual chat is bound to that repository. Never install into
both scopes.

Do not set HOME or CODEX_HOME, scan or copy authentication, or change
permissions, configuration, AGENTS files, marketplaces or caches.

1. Get the exact source

Use an exact clean checkout you can already reach, or retrieve the commit into a
new private directory. Do not touch the caller's own working checkout or
branch, or any Factory main checkout.

factory_source="<new private directory>"
git clone https://github.com/arcitai/factory.git "$factory_source" &&
  git -C "$factory_source" checkout --detach 477e6da1729a32ecc7a0af3ed424fa6bd63bc923
git -C "$factory_source" rev-parse HEAD 'HEAD^{tree}'
git -C "$factory_source" status --porcelain

Expect the commit and tree above, and empty status. If the clone does not contain
the commit, fetch exactly that commit from the same repository; do not substitute
another revision. A source archive works too, but its stage records no Git
provenance, so it is a different identity from the reviewed stage. Prefer the
pinned checkout.

2. Stage and verify

factory_stage_parent="<a private directory you own>"
factory_stage="$factory_stage_parent/factory-477e6da"
python3 "$factory_source/scripts/stage.py" all --output "$factory_stage"
sha256sum "$factory_stage/manifest.json"

The stage helper only stages, and it refuses an existing output. Check:

  1. The manifest's SHA-256 is 885b264c…8aca as above. With a clean pinned checkout
    and no line-ending or other normalization it should match exactly; if it
    differs, stop and compare before going further.
  2. manifest.json shows "bundle": "all", "factoryVersion": "0.1.20", the
    source commit as sourceRevision, "sourceModified": false, and 28 entries
    under files. skills/ holds nine folders.
  3. For every manifest entry under skills/factory-entry/ and
    skills/factory-foundation/ (11 in total: 2 and 9), run sha256sum on that
    staged file and compare it with its manifest value. The set of files on disk
    under those two folders must be exactly the set of manifest entries.
  4. Every one of those files is a regular, non-executable file; there are no
    symlinks. Each folder has its SKILL.md and LICENSE.

Keep the stage and its manifest privately; they are the recovery reference.

3. Preflight the destination

Do this only after the preview decision in Authority
names this account, host and scope.

Reuse facts you already hold; this is not a host inventory. For the selected
destination, privately record:

  • the exact destination directory, and for each of the two folder names whether
    it is absent (check both test ! -e and test ! -L, which catches a dangling
    symlink) or present, with its file set, modes and bytes;
  • any same-name factory-entry or factory-foundation the caller already sees in
    another scope, such as a repository's .agents/skills between its working
    directory and Git root, and any control that disables a skill. Read this from
    the caller's own supported skill listing. Do not assume absence from an older
    catalog;
  • who can recover the caller if this goes wrong, the authority you are acting
    under, and a checkpoint for any work this could affect.

Then decide each folder separately:

What you find Do
Absent Copy it in step 4
Present and identical to the stage (same file set and bytes) Verify, skip and record it as already installed
Present but different, locally edited, or ambiguous because the name exists in another scope Stop. Reconcile with the owner; do not overwrite or reinstall
A symlink, unreadable, or not a normal folder Stop, as above

4. Install the absent folders

This is setup section 5's reviewed copy recipe, applied to the two selected
folders. Run each line only for a folder you marked absent:

factory_skill_scope="<the owner's resolved Codex user skill directory>"
mkdir -p "$factory_skill_scope"
test ! -e "$factory_skill_scope/factory-entry" &&
  test ! -L "$factory_skill_scope/factory-entry" &&
  cp -R "$factory_stage/skills/factory-entry" "$factory_skill_scope/"
test ! -e "$factory_skill_scope/factory-foundation" &&
  test ! -L "$factory_skill_scope/factory-foundation" &&
  cp -R "$factory_stage/skills/factory-foundation" "$factory_skill_scope/"

The two copies are separate operations, not one atomic install. If a copy fails
or its result is uncertain, keep what is there, read it back and record it as
partial. Do not retry, force or remove anything; reconcile first.

Afterwards, compare each installed folder with the stage manifest as in step 2
(file set, sha256sum per file, regular non-executable files, SKILL.md,
references and LICENSE). Record requested and installed separately, and
confirm nothing else in the directory changed. Do not take a profile backup or
copy secrets.

5. Check native discovery and loading

Installed bytes prove installation only. Keep the next five results separate.
Each one needs observable evidence from the actual intended caller surface,
retained privately with the caller and session it came from and the time.

Result Accept as evidence Not evidence
Native listing The surface's own supported skill listing or selector visibly shows factory-entry and factory-foundation. Where it shows a location, that location is the destination read back in step 4 Files on disk; documentation
Native selection or invocation The surface's own supported selection or invocation of factory-entry, with its visible result. Codex documents /skills and $ selection in its CLI and IDE, and ChatGPT uses @; use only what the actual surface offers A CLI or IDE standing in for the actual surface; the model saying it invoked the skill
Current body and reference loading A result the surface itself shows, such as a native UI readback of the loaded skill or a visible native source or read-tool result. It must name the resolved source and show content from factory-entry's SKILL.md and from factory-foundation's setup reference. Compare that source and content with the installed files from step 4 and the stage manifest Correct answers about version 0.1.20, the routes, peer names or section titles, which this procedure and its context already supply; a model's statement that it "loaded" the skill
Explicit path loading (fallback) A visible read of an installed file by its path, compared with the manifest It is never native discovery, selection or loading; record it only as explicit loading
Useful real use Step 6 Correct routing alone does not show which source the caller used

For each observed result, record the caller (harness, surface, and the session or
thread as the surface identifies it), when it was observed, and which installed
file and stage manifest (885b264c…) its source matches. Use only support the
target surface actually has; there is no universal loader trace to ask for.

If the surface cannot show a result or bind it to the installed source, record
that result as UNKNOWN with:

  • the exact missing support or binding, such as "the listing shows names but no
    source location" or "the surface shows no read result";
  • the holder: the existing owner operator who keeps the private adoption record;
  • their next supported action that needs no escalation, such as checking again at
    the next ordinary session start, or using a readback the surface already offers.

Do not restart, open a new chat, change client, provider, model or mode, add a
grant or plugin, or run a new probe to manufacture a pass. The listing can be
observed while body loading stays UNKNOWN. An UNKNOWN holds only #91's
discovery and loading claim, not other work. This document cannot prove what the
current session loaded.

6. Use it once, for real

Under the owner's existing mandate, ask the caller one read-only Factory request,
for example: "Ask Factory's AgentOps for the current status of #91 and PR #92."
This is a status read, not an implementation assignment.

The caller should:

  1. Resolve the actual Factory AgentOps recipient from its native project,
    workspace and thread identity, and read that recipient's current state before
    sending.
  2. Send the request once, with a stable identity for it, and no duplicate dispatch.
  3. Record separately: queued, consumed, actually started, and the actual response.

The request can still be useful when body loading is UNKNOWN or the caller used
explicit path loading. Record it within that limit; it does not close #91's
discovery and loading claim.

Then ask it to explain, without sending anything, where an application request
would go, using the project identities in your adoption record. Any real
application communication stays with that application's own AgentOps and the
owner; this procedure does not start an application task.

For a host question, the caller explains the roles and any readiness gap from
#83's guidance. It runs no host trial.

At your next normal session, without any forced interruption, check that the
caller recovers the two skills, the recipients, its authority and the current
holds, and continues without replaying setup.

7. Recovery

Keep the preflight record and the stage manifest privately. This procedure only
ever adds folders that were absent, so rollback covers exactly those folders:

  1. Wait until the caller is safely idle.
  2. Confirm the folder's bytes still match the stage manifest. If they changed,
    stop and reconcile.
  3. Move each folder this adoption created into a private recovery directory
    outside any skill discovery scope. Do not delete broadly.

Never touch a folder that existed before, was skipped, or belongs to another
project. A running session may keep a skill it already loaded, so check
discovery again separately; removing files from disk does not prove the
conversation unloaded it. No cache edits, restarts or grants.

Authority and current holds

Under #88 there are two separate decisions:

  • Source delivery: merging PR Clarify host setup and maintenance ownership #85 (head 088e099…) and PR Add a portable owner-agent entry for Factory #92 (head 477e6da…)
    is a human decision. It follows the stack order and branch protection, which
    requires Method checks. A technical ACCEPT or green CI is not permission.
    Status: pending.
  • Preview adoption: the owner may separately authorize installing these two
    folders from the unmerged, immutable commit 477e6da…. The authorization must
    name the owner account, host and native scope (user or project). It need not
    wait for merge or release, and it does not include merge, release, or any host or
    app restart. Status: not yet given.

Record each decision as pending, declined or unknown; silence is not approval. A
changed head, destination or scope needs the decision assessed again. No release
is requested.

Other holds:

#91 stays open until the real discovery, loading, use and resume outcomes below
are recorded. The six synthetic caller cases in PR #92 are source evidence, not
live use.

Receipt

Fill this in privately. Publish only a sanitized summary: no raw owner content,
credentials or host identities. Each result is observed, UNKNOWN or not run, with
a link to its retained private evidence.

Item Expected Result and evidence
Candidate Commit 477e6da…, tree dd2a112…, manifest 885b264c…
Preview authority Named account, host and scope; date
Observation context Caller harness, surface, and session or thread as the surface identifies it; time
Preflight Each folder absent, identical or stopped; same-name check
Copied, skipped or partial Per folder, with private manifest comparison
Installed readback 11 files match the manifest; modes and licenses correct
Native listing Both names in the actual surface's own listing; location matches the installed destination where shown
Native selection or invocation The surface's own selection or invocation of factory-entry and its visible result
Current body and reference Surface-shown source and content for the entry SKILL.md and the Foundation setup reference, bound to the installed files and manifest
Explicit path loading Used or not; recorded only as explicit loading
Gaps For each UNKNOWN: missing support or binding, holder, next action
Real request Recipient resolved; queued, consumed, started and response recorded; loading status it relied on
Application route Explained only, from recorded project identities
Normal resume Skills, recipients, authority and holds recovered
Limits Anything not run or not proven
Recovery Not needed, or which created folders were moved, and where privately

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant