Project Instantiation Workflow
This doc explains the workflow before a target ASK repo exists, and how that upstream phase transitions into normal operational use.
It is agent-agnostic. ASK projects run the adversarial-collaboration operating model — an ASK-apexed advisor–executor topology: ASK as the source-of-intent and authorization apex, a non-writing advisor surface, and a repo-attached execution surface (currently a GPT advisor and Claude Code as executor; model identity is operational, not architectural). Direct execution — ASK driving the executor without an advisor pass where a separate pass would not materially reduce uncertainty — is a bounded variant within that model, not a separate model. The earlier split-execution model (ChatGPT as prompt compiler, Codex as executor, Claude Code as optional advisor — historically Model A) is retired as a live option and is not offered to any project. See README.md §Operating Model and docs/architecture.md.
on this page
Phases
1. Instantiation
Use this phase when the project is being defined and the target repo does not yet exist.
During instantiation:
- read whatever instantiation source pack exists (Project source pack in ChatGPT, conversation context in Claude Code, or both)
- use
apexSolarKiss/control-surfaceas the master reference repo - use
apexSolarKiss/asset-pipeline-ASKas the primary working example - refine project purpose, repo name, repo description, and initial structure
- confirm the advisor configuration — the operating model is not a per-project choice. Record whether an external advisor surface is configured, who occupies it, and which classes of work trigger advisor review. Direct execution is a bounded task-level path and remains available even when an advisor surface is configured
- decide which assets should remain external versus which should eventually live in the repo
- decide where the external grounding note will live (path outside the repo)
- determine whether the project has a domain authority in a role distinct from the architect/operator — a person or role that supplies or validates binding judgment within a named domain; if so, it adopts the domain-authority review profile at bootstrap (see
docs/domain-authority-review-protocol.md)
At this point, there is no repo-local truth yet because the target repo does not exist. The instantiation prompt is prompts/project-instantiation-initial-prompt.md.
2. Bootstrap
Use this phase once the target repo exists and the first repo-local files can be established.
During bootstrap:
-
verify the new repo attachment
-
create the project's external surface with its four planes, per the setup step in
README.md:<project-name>-EXTERNAL/ <project-name>_grounding-note.md # canonical durable context (root) scratch/ # _vN snapshots + iteration intent-carriers/ # standing + invocable carrier canonicals (unversioned) ZZZ/ # frozen _vN snapshots + retired / historical carrier lineage intent-INbox/ # inbound routed handoffs, under the filename lifecycle _STATE.md # structural inbox state — not routed intentA newly instantiated
_STATE.mdbegins asOPEN— no additional inbox hold, ordinary governed ingestion may proceed. Its full schema and the structural-exemption contract are owned bydocs/advisor-project-surface-architecture.md(LIFE-4g) and stated operationally intemplates/advisor-project-bootstrap.template.mdandtemplates/_INDEX-project.template.md— do not restate them here.In
intent-carriers/, the unversioned current canonical mirrors the latest accepted_vN;ZZZ/holds the frozen_vNsnapshots and any retired or historical carrier variants. A prior_vNis historical, not superseded — carrier families are revised, retired, or replaced, and existing legacy filenames are preserved unchanged. Adapted prompts and other invocable carriers go inintent-carriers/; routed handoffs from another operating surface go inintent-INbox/, and never the reverse. -
copy
templates/AGENTS.template.mdinto the repo asAGENTS.md— the payload-free shell — and adapt its project-specific defaults (the local delta) -
resolve the shared execution protocol into that
AGENTS.md: insert the shared body fromprotocol/AGENTS.shared.mdverbatim between the shell'sBEGIN/ENDshared markers, so each consumer resolves the block locally inside its own already-requiredAGENTS.mdrather than holding a separate copy; then add the applicableprotocol/profiles/*.mdand any opt-inprotocol/fragments/*.md(e.g.protocol/fragments/standing-upstream-conformance-grant.md).protocol/manifest.jsonis the normative registry of these pieces, andprotocol/check.shvalidates the resolvedAGENTS.mdlocally (a deterministic local validator, not CI) -
copy
templates/grounding-note.template.mdinto the external grounding-note location and fill in intent, audience, philosophy, foundational premises, and durable loose threads -
optionally copy
templates/architecture.template.mdinto the repo asdocs/architecture.md -
for any Claude-operated repo, copy
templates/CLAUDE.template.mdinto the repo asCLAUDE.md. It is required, not optional: Claude Code readsCLAUDE.md, notAGENTS.md, so the adapter's@AGENTS.mdimport is what actually delivers the resolved carrier into context. Exactly one@AGENTS.mdimport; repo-specific Claude prose may follow it. Verify the new repo's adapter directly —@AGENTS.mdoccurs exactly once, repo-localCLAUDE.mdprose is preserved, and a fresh session's/contextreceipt showsAGENTS.mdimported. (protocol/adapters/claude-code/check-claude-adapter.shis an owner-side check of control-surface's own adapter, template, and settings fragment; it does not run against a consumer repo) -
if the project profile is architecture-uncertain (ontology-first work, prototypes as pressure surfaces, deferred schema commitment, modeling-before-planning, ceremony-budget pressure), optionally adopt
templates/overlays/architecture-uncertain-rules.template.mdon top of the baseAGENTS.md; skip when the task surface is known and the work is execution against it -
if the project has a domain authority distinct from the architect/operator (determined at instantiation), copy
templates/domain-authority-review-profile.template.mdinto the project's operator-side surface and followdocs/domain-authority-review-protocol.mdto keep the reviewer's authority, the project stage, and implementation authority independent, classify returned claims by stage, and route judgment to execution; skip when the project's source of intent is authored entirely by the architect/operator -
if any hosted Project surface governed by
docs/advisor-project-surface-architecture.mdis planned — an ASK-facing repo-advisor Project or a hosted domain-authority review Project alike — decide that exact hosted Project instance's memory scope before the Project is created, and record it — per instance — with its rationale in that variant's Project configuration record, outside the pasted Instructions fence. Both variants use the same deployment shape and therefore inherit the same requirement; only the carrier differs — a repo-advisor instance records it in the Instructions template's outside-fence section, a domain-authority review instance in its own operator configuration canonical. Personal-context Projects are separately governed across the wall and are out of scope here. The instance is the configuration unit; the role or function it serves is the rationale, and two instances serving one broad role may correctly differ. The current host does not permit changing scope in place, so an unrecorded default is a decision made by omission. A continuity function may choose the host default; a contextual-isolation function chooses Project-only and the empty-Project workflow, because Project-only alone does not make a new thread fresh. There is no universally correct value — HOST-1 and A13 own the requirement, and this step is where the decision is made rather than inherited -
identify the first repo-local entry points
-
run the post-bootstrap grounding-note trim pass per
templates/grounding-note.template.mdonce the repo carries project truth — remove or relocate fast-aging material (repo-state chronology, planning-packet instructions, "future repo" language, bootstrap-stage task sequencing) that the pre-repo grounding note may have accumulated
This is the phase where repo-local truth begins to exist. The transition prompt is prompts/claude-code-initial-prompt.md — executor-side bootstrap under the current operating model.
The retired Model-A prompt pair (prompts/control-surface-initial-prompt.md, prompts/codex-initial-prompt.txt) remains in the repo as frozen historical provenance. It is not a bootstrap path.
3. Operational
Use this phase once the target repo has active repo-local docs and normal work can proceed.
During operational use:
- treat repo-local files as the source of truth for work inside the repo
- treat the external grounding note as the source of truth for repo-external context
- use prompts for startup or handoff, not as permanent repo policy
- treat per-conversation state (ChatGPT thread history, task lists, in-flight session context) as ephemeral — do not promote it into the durable sources
- treat Claude Code auto memory (
MEMORY.mdand its topic files) as a non-authoritative, read-mostly operator cache — persistent, not ephemeral, never a durable owner, and every mutation governed byAGENTS.md§Learning Disposition and §Private-Memory Write Gate - when an external advisor surface is used (GPT or Claude in chat form):
- create
<project-name>-EXTERNAL/_INDEX-<project-name>.mdfromtemplates/_INDEX-project.template.md— a source index / path map listing the project's canonical Dropbox paths, their status classes, and the wall rules (use_INDEX-<project-name>-<role>.mdfor role-specific advisor surfaces). It is fetched live at the locator the bootstrap declares, not mounted; the advisor fetches canonicals live from Dropbox by exact path, and any mounted copies are connector-failure fallback only. When the project'sAGENTS.mdresolves the shared execution protocol, the index must carry the template's Shared execution-protocol architecture rows — owner model, shared body, normative manifest, propagation runbook, and, where the surface is authorized to read it, the live protocol-consumer ledger; the advisor preflight requires those files, so an index without the rows leaves the advisor no route to them. Skip the index for a project with no advisor surface. - generate the surface bootstrap from
templates/advisor-project-bootstrap.template.mdand mount it as the advisor Project's single standing Source; install the thin pre-bootstrap floor fromtemplates/advisor-project-instructions.template.mdonce into the Project Instructions — not pasted per thread (seedocs/critique-protocol.md). The Instructions floor points at the mounted bootstrap as the first read; the bootstrap points at the live index; the grounding-note canonical lives at the-EXTERNALroot. Placement contract and acceptance tests:docs/advisor-project-surface-architecture.md. - for exact-byte advisor review, the normal repo review object is the pushed PR once it exists; in the paired path, Stage-1 readiness includes the minimum exact review object — before reporting
exact scoped diff ready for approval, the executor publishes a named-PROPOSEDreview object — or, when a target is not representable as a text patch, a declared review bundle (ordered exact-object or patch parts, one per target, each hashed) — to the project's mapped shared scratch (<project-name>-EXTERNAL/scratch/), reporting its exact path, baseline, byte size, and SHA-256, or identifies an already advisor-readable exact surface. ASK's relay of the readiness receipt opens pre-PR advisor review — the relay is the request; Direct execution requires an explicit ASK authorization (aFYIorHOLDenvelope suppresses the advisor verdict but authorizes nothing; silence or non-relay elects nothing), and a summary relayed without the object leaves review open with readiness incomplete and one publication request to the executor. A reported review object is immutable and a revision takes a new-PROPOSEDname. Retrieval order: exact path → raw bytes → one bounded alternate representation. Resolving the path proves reachability, not fidelity — extracted text, previews, and normalized views are inspection representations, and path metadata or a lossy view is not exact-byte availability. Do not use ASK as a byte courier while exact bytes remain retrievable through the authorized mapped route; manual operator upload is fallback only after both rungs have failed and been reported and ASK explicitly elects it, for content already authorized to the advisor, and never to cross a wall (AGENTS.md§Advisor-Readable Review Objects; advisor bootstrap §Verification;_INDEXscratch row)
- create
- when the project will use the advisor / nudge / critique surfaces, adapt the protocol repo's reusable nudge prompt (
prompts/repo-nudge-prompt.md) and the repo critique cycle prompts (prompts/repo-critique-initial-prompt.md,prompts/repo-critique-synthesis-prompt.md,prompts/repo-critique-execution-prompt.md) into project-flavored operator-side copies in<project-name>-EXTERNAL/intent-carriers/— an adapted prompt is an invocable carrier, not a routed handoff, so it never lands in the intent inbox and never takes a lifecycle suffix; the protocol repo's prompts remain canonical, the operator-side copies are project-flavored adaptations
What Stays External
Keep these external unless a project has a deliberate reason to mirror them:
- the grounding note (always external, by design)
- the advisor Project's mounted bootstrap, its thin Instructions deployment canonical, and its live-fetched index canonical, when an external advisor surface (GPT or Claude in chat form) is used — the index is not mounted, but it stays external and required
- startup prompts used to frame or hand off work
What Usually Becomes Repo-Local
Once the repo exists, these are typical local candidates:
AGENTS.md(always)CLAUDE.mdadapter (required for Claude-operated repos; importsAGENTS.md)- a project architecture doc
- project-specific entry-point docs
Practical Output
The normal output of instantiation is not code yet.
It is a ready-to-send next prompt that can:
- create or attach the target repo
- copy and adapt the relevant templates
- begin bootstrap using the agreed project purpose, structure, and advisor-surface decision