Skip to content

feat: add safe guided project onboarding #73

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
roodboi merged 6 commits into from
Jul 29, 2026
Merged

feat: add safe guided project onboarding #73

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ccb4a57
feat: add safe guided project onboarding
roodboi Jul 29, 2026
531e948
feat: harden guided project onboarding
roodboi Jul 29, 2026
60cd660
fix: close final onboarding review gaps
roodboi Jul 29, 2026
3ac723b
fix: retry mutation lock observation races
roodboi Jul 29, 2026
df4ffac
fix: bound enrollment preview inputs
roodboi Jul 29, 2026
8e28fe4
fix: fail closed for unsupported project setup
roodboi Jul 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 24 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,17 +91,17 @@ fclt --version

The npm package is named `facult` for registry compatibility. The command is `fclt`.

Then bootstrap the complete writeback/evolution loop from your home directory or a repository:
Then bootstrap the global writeback/evolution loop:

```bash
fclt setup
```

That one command safely initializes or updates global `~/.ai`, initializes the current git
repository's `<repo>/.ai` when applicable, creates review-state paths, rebuilds capability
discovery, and installs the Codex plugin when Codex is available. It preserves local edits and
existing WB/EV history, and it is safe to run again. Use `fclt setup --global-only` outside a
project or `fclt setup --no-codex-plugin` for a CLI-only install.
That command safely initializes or updates global `~/.ai`, creates review-state paths, rebuilds
capability discovery, and installs the Codex plugin when Codex is available. It does not initialize
the current repository. It preserves local edits and existing WB/EV history, and it is safe to run
again. Use `fclt setup --include-project` to include a no-write project enrollment plan, or
`fclt setup --no-codex-plugin` for a CLI-only install.

One-off usage:

Expand Down Expand Up @@ -265,14 +265,23 @@ fclt templates init operating-model --global --update --dry-run
fclt templates init operating-model --global --update
```

Create a repo-local `.ai` root:
Preview and apply a minimal repo-local `.ai` root:

```bash
cd /path/to/repo
fclt templates init project-ai
fclt project init --json
fclt project init --apply --plan-sha <sha-from-preview> --json
fclt status --project
```

Minimal enrollment never copies `AGENTS.md` or `CLAUDE.md`. Use
`--guidance AGENTS.md` only for an explicit, fully previewed reference to a
tracked clean rulebook. Full operating-pack install remains a separate
`fclt templates init operating-model --project` action.
Project discovery, status, and rollback preview remain read-only on Windows;
project enrollment and registry-mutating lifecycle actions currently require
Linux or macOS conditional replacement support.

Create individual capability units:

```bash
Expand Down Expand Up @@ -566,7 +575,12 @@ Keep tracked MCP config secret-free. Use local overlays such as `mcp/servers.loc
Discovery:

```bash
fclt setup [--global-only] [--no-codex-plugin] [--json]
fclt setup [--include-project] [--no-codex-plugin] [--json]
fclt projects discover --root <path> [--root <path>] [--since <duration>] [--json]
fclt projects status [--root <path>] [--json]
fclt project init [--project-root <path>] [--guidance <path>] [--apply --plan-sha <sha>] [--json]
fclt project disable|ignore|inactive|remove [--project-root <path>] [--json]
fclt project rollback --receipt <id> [--apply] [--json]
fclt status [--json]
fclt doctor [--json] [--repair]
fclt paths [--json]
Expand All @@ -585,7 +599,7 @@ Canonical store:
```bash
fclt templates list
fclt templates init operating-model [--global|--project|--root PATH] [--update]
fclt templates init project-ai [--update]
fclt templates init project-ai [--project-root PATH|--root PATH] [--guidance PATH] [--apply --plan-sha SHA]
fclt templates init instruction <name>
fclt templates init snippet <marker>
fclt templates init skill <name>
Expand Down
10 changes: 8 additions & 2 deletions docs/built-in-pack.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,13 +76,19 @@ fclt templates init operating-model --global --update

`--update` refreshes only files that still match the last installed pack manifest and skips local edits. See [Built-in pack upgrades](./pack-upgrades.md).

Use `project-ai` when the target is the current repo:
Use guided onboarding when the target needs only a minimal project layer:

```bash
cd /path/to/repo
fclt templates init project-ai
fclt project init --json
fclt project init --apply --plan-sha <sha-from-preview> --json
```

This writes the protective `.ai/.gitignore` before generated state and does
not install this full pack or copy repo guidance. Use
`fclt templates init project-ai` only as the equivalent preview-first legacy
alias.

Legacy managed mode is a deprecated rendering layer. Inspect its plan without changing tool state:

```bash
Expand Down
6 changes: 3 additions & 3 deletions docs/codex-plugin-capability-matrix.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
"matrixVersion": 1,
"generatedFrom": {
"packageVersion": "2.28.0",
"pluginVersion": "0.1.2",
"pluginVersion": "0.1.3",
"auditedAt": "2026-07-14T00:00:00Z"
},
"dispositions": ["exposed", "withheld", "blocked_safer_api"],
Expand Down Expand Up @@ -172,7 +172,7 @@
"risk": "reversible_mutation",
"scope": "explicit global|global_and_project plus project cwd",
"preview": "default; calls released setup --dry-run JSON contract",
"apply": "dryRun=false plus approve=true against the released setup contract",
"apply": "dryRun=false plus approve=true applies global setup; project enrollment remains a separate plan-hash CLI action",
"rollback": "preserved existing capability state and reported repair actions",
"verification": "doctor loop readiness plus fresh-session plugin discovery"
},
Expand Down Expand Up @@ -225,7 +225,7 @@
},
{
"id": "templates.init_operating_model",
"cli": "templates init operating-model|project-ai",
"cli": "project init|projects discover|projects status|templates init operating-model",
"cliAvailability": "available",
"mcp": {
"disposition": "exposed",
Expand Down
18 changes: 10 additions & 8 deletions docs/codex-plugin.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,11 +76,13 @@ For a new install, prefer the complete one-command bootstrap:
fclt setup
```

It prepares global and current-repo capability, review state, indexes, and the plugin. The same
command is available to Codex through `fclt_setup`, so a plugin-led install does not require the
user to know capability roots or state paths. The MCP form requires an explicit `global` or
`global_and_project` scope, defaults to dry-run, requires an explicit project `cwd`, and only
applies when `dryRun: false` and `approve: true` are both present.
It prepares global capability, review state, indexes, and the plugin. The same
command is available to Codex through `fclt_setup`, so a plugin-led install
does not require the user to know global state paths. The MCP form requires an
explicit `global` or `global_and_project` scope and defaults to dry-run.
`global_and_project` requires an explicit project `cwd` and returns the exact
no-write minimal enrollment plan. Applying that project plan remains a
separate CLI action requiring its returned plan hash.

Use the narrow plugin-only command when the CLI loop is already healthy:

Expand All @@ -103,9 +105,9 @@ inherit the shell that contains Node, Bun, mise, or a package-manager shim.
When the `codex` command is available, setup runs
`codex plugin add fclt@<marketplace> --json`. Codex installs the plugin cache
under `~/.codex/plugins/cache/<marketplace>/fclt/` using its own version
directory. The read-only audit capability gate ships in plugin `0.1.2`; its
version bump prevents Codex from selecting the pre-gate `0.1.1` cached wrapper
after an upgrade. Setup fails closed unless Codex's install result, installed
directory. The safe project-onboarding contract ships in plugin `0.1.3`; its
version bump prevents Codex from selecting the pre-onboarding `0.1.2` cached
wrapper after an upgrade. Setup fails closed unless Codex's install result, installed
payload hash, and post-install plugin list all select the bundled version as
installed and enabled.

Expand Down
13 changes: 10 additions & 3 deletions docs/pack-upgrades.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,9 +58,16 @@ The pack source stores the composed entry template at `snippets/templates/agents

That installed `AGENTS.global.md` is not meant to hold every rule.

If first install finds existing agent guidance, `fclt` seeds `AGENTS.global.md` from it and appends the Facult operating-model frame. Global installs look for existing global tool docs such as `~/.codex/AGENTS.md` and `~/.claude/CLAUDE.md`; project installs look for repo-local `AGENTS.md` or `CLAUDE.md`.

Seeded files are user-owned. They are intentionally excluded from the pack manifest so `--update` skips them unless you explicitly replace them with `--force` or edit them manually.
On a global first install, `fclt` can seed `AGENTS.global.md` from existing
global tool docs such as `~/.codex/AGENTS.md` and
`~/.claude/CLAUDE.md`, then append the Facult operating-model frame. Project
installs never seed from repo-local `AGENTS.md` or `CLAUDE.md`; those files
remain canonical repository guidance and require explicit reviewed
`fclt project init --guidance <path>` reference adoption.

Globally seeded files are user-owned. They are intentionally excluded from the
pack manifest so `--update` skips them unless you explicitly replace them with
`--force` or edit them manually.

Use:

Expand Down
Loading
Loading