@ai-outfitter/outfitter 1.2.0 → 1.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agents/PiSessionDirectory.d.ts +16 -0
- package/dist/agents/PiSessionDirectory.js +41 -0
- package/dist/agents/PiSessionDirectory.js.map +1 -0
- package/dist/cli/commands/RunAgentCommand.d.ts +2 -0
- package/dist/cli/commands/RunAgentCommand.js +20 -1
- package/dist/cli/commands/RunAgentCommand.js.map +1 -1
- package/dist/projection/ProjectHarness.js +51 -4
- package/dist/projection/ProjectHarness.js.map +1 -1
- package/dist/projection/Projection.d.ts +8 -0
- package/docs/documentation/concepts.md +1 -1
- package/docs/documentation/personas.md +33 -7
- package/docs/documentation/state.md +28 -1
- package/docs/documentation/usecases/persona-reviews.md +6 -5
- package/package.json +1 -1
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* pi's session-storage environment override. pi resolves the session directory as
|
|
3
|
+
* `--session-dir` → `PI_CODING_AGENT_SESSION_DIR` → `sessionDir` in settings.json, so a
|
|
4
|
+
* pass-through `-- --session-dir <dir>` still wins over the default Outfitter sets here.
|
|
5
|
+
*/
|
|
6
|
+
export declare const PI_SESSION_DIRECTORY_ENV = "PI_CODING_AGENT_SESSION_DIR";
|
|
7
|
+
/** pi's durable session folder for one project: `~/.pi/agent/sessions/--<encoded project>--`. */
|
|
8
|
+
export declare const resolvePiUserSessionDirectory: (homeDirectory: string, projectDirectory: string) => string;
|
|
9
|
+
/**
|
|
10
|
+
* Session directory for a pi launch, or `undefined` when the launch should keep whatever
|
|
11
|
+
* `PI_CODING_AGENT_SESSION_DIR` it inherits — an explicitly configured store, such as a resident
|
|
12
|
+
* agent's workspace/PVC path, stays in control. `env`, `homeDirectory`, and `projectDirectory` are
|
|
13
|
+
* injected so the resolution stays unit-testable; `projectDirectory` is the directory pi runs in
|
|
14
|
+
* (`process.cwd()`), which is what makes the result pi's own folder for the project.
|
|
15
|
+
*/
|
|
16
|
+
export declare const resolvePiSessionDirectory: (env: Readonly<Record<string, string | undefined>>, homeDirectory: string, projectDirectory: string) => string | undefined;
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
// Keeps pi session transcripts durable across runs. Outfitter launches pi with PI_CODING_AGENT_DIR
|
|
2
|
+
// pointed at a per-run projection root that is deleted once the child exits, and pi stores sessions
|
|
3
|
+
// under `<agent dir>/sessions/<encoded cwd>` by default (pi-coding-agent core/session-manager.js:
|
|
4
|
+
// getDefaultSessionDirPath()). Left alone every transcript dies with the projection, so
|
|
5
|
+
// `pi --continue`/`--resume` can never find the previous conversation (#223).
|
|
6
|
+
//
|
|
7
|
+
// Outfitter therefore points pi at the same per-project folder under pi's durable agent directory
|
|
8
|
+
// that a standalone pi already writes to, so history is shared between `outfitter run` and a bare
|
|
9
|
+
// `pi` in the same project, and `--continue` keeps pi's fast path instead of scanning every
|
|
10
|
+
// project's transcripts.
|
|
11
|
+
import { join, resolve } from 'node:path';
|
|
12
|
+
import { resolvePiUserAgentDirectory } from './PiCredentialPersistence.js';
|
|
13
|
+
/**
|
|
14
|
+
* pi's session-storage environment override. pi resolves the session directory as
|
|
15
|
+
* `--session-dir` → `PI_CODING_AGENT_SESSION_DIR` → `sessionDir` in settings.json, so a
|
|
16
|
+
* pass-through `-- --session-dir <dir>` still wins over the default Outfitter sets here.
|
|
17
|
+
*/
|
|
18
|
+
export const PI_SESSION_DIRECTORY_ENV = 'PI_CODING_AGENT_SESSION_DIR';
|
|
19
|
+
// pi's own encoding of a project directory into a single session folder name: absolute path,
|
|
20
|
+
// leading separator dropped, remaining separators and drive colons flattened to '-', wrapped in
|
|
21
|
+
// '--'. Mirrored here so Outfitter runs share pi's native per-project folder rather than starting a
|
|
22
|
+
// parallel layout.
|
|
23
|
+
const encodeProjectDirectory = (projectDirectory) => `--${resolve(projectDirectory)
|
|
24
|
+
.replace(/^[/\\]/u, '')
|
|
25
|
+
.replace(/[/\\:]/gu, '-')}--`;
|
|
26
|
+
/** pi's durable session folder for one project: `~/.pi/agent/sessions/--<encoded project>--`. */
|
|
27
|
+
export const resolvePiUserSessionDirectory = (homeDirectory, projectDirectory) => join(resolvePiUserAgentDirectory(homeDirectory), 'sessions', encodeProjectDirectory(projectDirectory));
|
|
28
|
+
/**
|
|
29
|
+
* Session directory for a pi launch, or `undefined` when the launch should keep whatever
|
|
30
|
+
* `PI_CODING_AGENT_SESSION_DIR` it inherits — an explicitly configured store, such as a resident
|
|
31
|
+
* agent's workspace/PVC path, stays in control. `env`, `homeDirectory`, and `projectDirectory` are
|
|
32
|
+
* injected so the resolution stays unit-testable; `projectDirectory` is the directory pi runs in
|
|
33
|
+
* (`process.cwd()`), which is what makes the result pi's own folder for the project.
|
|
34
|
+
*/
|
|
35
|
+
export const resolvePiSessionDirectory = (env, homeDirectory, projectDirectory) => {
|
|
36
|
+
const inherited = env[PI_SESSION_DIRECTORY_ENV];
|
|
37
|
+
if (inherited !== undefined && inherited.trim() !== '')
|
|
38
|
+
return undefined;
|
|
39
|
+
return resolvePiUserSessionDirectory(homeDirectory, projectDirectory);
|
|
40
|
+
};
|
|
41
|
+
//# sourceMappingURL=PiSessionDirectory.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"PiSessionDirectory.js","sourceRoot":"","sources":["../../src/agents/PiSessionDirectory.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,oGAAoG;AACpG,kGAAkG;AAClG,wFAAwF;AACxF,8EAA8E;AAC9E,EAAE;AACF,kGAAkG;AAClG,kGAAkG;AAClG,4FAA4F;AAC5F,yBAAyB;AACzB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAC;AAE3E;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,6BAA6B,CAAC;AAEtE,6FAA6F;AAC7F,gGAAgG;AAChG,oGAAoG;AACpG,mBAAmB;AACnB,MAAM,sBAAsB,GAAG,CAAC,gBAAwB,EAAU,EAAE,CAClE,KAAK,OAAO,CAAC,gBAAgB,CAAC;KAC3B,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC;KACtB,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,IAAI,CAAC;AAElC,iGAAiG;AACjG,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,aAAqB,EAAE,gBAAwB,EAAU,EAAE,CACvG,IAAI,CAAC,2BAA2B,CAAC,aAAa,CAAC,EAAE,UAAU,EAAE,sBAAsB,CAAC,gBAAgB,CAAC,CAAC,CAAC;AAEzG;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CACvC,GAAiD,EACjD,aAAqB,EACrB,gBAAwB,EACJ,EAAE;IACtB,MAAM,SAAS,GAAG,GAAG,CAAC,wBAAwB,CAAC,CAAC;IAChD,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IAEzE,OAAO,6BAA6B,CAAC,aAAa,EAAE,gBAAgB,CAAC,CAAC;AACxE,CAAC,CAAC"}
|
|
@@ -19,6 +19,8 @@ export interface RunAgentInput {
|
|
|
19
19
|
readonly harness?: string;
|
|
20
20
|
readonly strict?: boolean;
|
|
21
21
|
readonly passThroughArgs?: readonly string[];
|
|
22
|
+
/** `--append-prompt` documents appended to the system prompt after the agent's own, in order. */
|
|
23
|
+
readonly appendPromptPaths?: readonly string[];
|
|
22
24
|
readonly launcher: AgentProcessLauncher;
|
|
23
25
|
/** Onboarding to run once when no agent is selected and settings define no `default_agent`. */
|
|
24
26
|
readonly setup?: SetupRunner;
|
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
// `outfitter run [agent]` — resolve → compose → project → launch on the .agents model.
|
|
2
|
-
import { mkdtempSync, rmSync } from 'node:fs';
|
|
2
|
+
import { mkdtempSync, rmSync, statSync } from 'node:fs';
|
|
3
3
|
import { tmpdir } from 'node:os';
|
|
4
4
|
import { join } from 'node:path';
|
|
5
5
|
import { Option } from 'commander';
|
|
6
6
|
import { launchThroughSpawn, spawnLauncher } from '../../agents/AgentLaunch.js';
|
|
7
7
|
import { persistPiCredentials, resolvePiUserAgentDirectory, seedPiCredentials, } from '../../agents/PiCredentialPersistence.js';
|
|
8
|
+
import { resolvePiSessionDirectory } from '../../agents/PiSessionDirectory.js';
|
|
8
9
|
import { compose } from '../../composer/Composer.js';
|
|
9
10
|
import { ensurePiExtensions } from '../../extensions/PiExtensionCache.js';
|
|
10
11
|
import { resolveOutfitterCacheDir } from '../../paths/OutfitterCache.js';
|
|
@@ -51,6 +52,10 @@ const launchWithCredentialPersistence = async (input, harness, rootDirectory, la
|
|
|
51
52
|
persistPiCredentials(rootDirectory, piUserAgentDirectory);
|
|
52
53
|
return exitCode;
|
|
53
54
|
};
|
|
55
|
+
// pi writes sessions inside PI_CODING_AGENT_DIR — the projection root Outfitter deletes after the
|
|
56
|
+
// run — so resolve pi's durable per-project store instead and let `--continue` outlive the run. An
|
|
57
|
+
// inherited PI_CODING_AGENT_SESSION_DIR keeps precedence (undefined), as do non-pi harnesses.
|
|
58
|
+
const resolveSessionDirectory = (input, harness) => harness === 'pi' ? resolvePiSessionDirectory(process.env, input.homeDirectory, input.projectDirectory) : undefined;
|
|
54
59
|
// Installs/caches the pi extensions for the composed agent (pi only) so they load at launch.
|
|
55
60
|
const resolvePiExtensions = async (input, harness, extensionSpecs) => {
|
|
56
61
|
if (harness !== 'pi')
|
|
@@ -62,6 +67,15 @@ const resolvePiExtensions = async (input, harness, extensionSpecs) => {
|
|
|
62
67
|
});
|
|
63
68
|
};
|
|
64
69
|
const piConfigurationOverlays = (plan, selectedAgent) => [...(plan.contributingAgents ?? [selectedAgent])].reverse().flatMap((agent) => agent.piConfigDirectories ?? []);
|
|
70
|
+
// Validated before launch rather than inside projection: pi never reads these paths itself, so an
|
|
71
|
+
// unreadable one would otherwise fail differently per harness — a raw ENOENT out of the Claude
|
|
72
|
+
// concatenation, and a harness-generated error on pi.
|
|
73
|
+
const assertReadableAppendPrompts = (paths) => {
|
|
74
|
+
const unreadable = (paths ?? []).filter((path) => statSync(path, { throwIfNoEntry: false })?.isFile() !== true);
|
|
75
|
+
if (unreadable.length > 0) {
|
|
76
|
+
throw new Error(`--append-prompt: not a readable file: ${unreadable.join(', ')}`);
|
|
77
|
+
}
|
|
78
|
+
};
|
|
65
79
|
export const executeRunAgentCommand = async (input) => {
|
|
66
80
|
// Flush messages to the terminal (before launch); they are also returned so callers can inspect them.
|
|
67
81
|
const emit = (messages) => {
|
|
@@ -70,6 +84,7 @@ export const executeRunAgentCommand = async (input) => {
|
|
|
70
84
|
};
|
|
71
85
|
let resolved = resolveEffectiveSet(input);
|
|
72
86
|
assertNoSettingsIssues(resolved.settingsIssues);
|
|
87
|
+
assertReadableAppendPrompts(input.appendPromptPaths);
|
|
73
88
|
emit(resolved.warnings.map((warning) => `warning: ${warning}`));
|
|
74
89
|
// First run: nothing selected and no default configured — onboard, then resolve again.
|
|
75
90
|
const setupMessages = [];
|
|
@@ -103,7 +118,9 @@ export const executeRunAgentCommand = async (input) => {
|
|
|
103
118
|
harness,
|
|
104
119
|
rootDirectory,
|
|
105
120
|
homeDirectory: input.homeDirectory,
|
|
121
|
+
sessionDirectory: resolveSessionDirectory(input, harness),
|
|
106
122
|
passThroughArgs: input.passThroughArgs,
|
|
123
|
+
appendPromptPaths: input.appendPromptPaths,
|
|
107
124
|
extensionLoadDirs: harness === 'pi' ? extensions.loadDirs : undefined,
|
|
108
125
|
// ProjectHarness only overlays these for the pi harness, so pass them through unconditionally.
|
|
109
126
|
configurationOverlayDirectories: configurationOverlays,
|
|
@@ -157,6 +174,7 @@ export const createRunAgentCommand = (dependencies = {}) => ({
|
|
|
157
174
|
.argument('[args...]', 'Arguments passed through to the harness after --.')
|
|
158
175
|
.addOption(new Option('--harness <harness>', 'Harness to launch.').choices([...HARNESSES]))
|
|
159
176
|
.option('--strict', 'Treat composition warnings and unsupported loadout elements as fatal.')
|
|
177
|
+
.option('--append-prompt <path>', 'Append a Markdown document to the system prompt. Repeatable; applied in the order given.', (value, previous = []) => [...previous, value])
|
|
160
178
|
.allowUnknownOption(true)
|
|
161
179
|
.action(async (agent, passThroughArgs, options) => {
|
|
162
180
|
/* v8 ignore next 3 -- process/launcher defaults are exercised by the CLI entrypoint, not unit tests. */
|
|
@@ -170,6 +188,7 @@ export const createRunAgentCommand = (dependencies = {}) => ({
|
|
|
170
188
|
harness: options.harness,
|
|
171
189
|
strict: options.strict,
|
|
172
190
|
passThroughArgs,
|
|
191
|
+
appendPromptPaths: options.appendPrompt,
|
|
173
192
|
launcher,
|
|
174
193
|
setup: dependencies.setup ?? interactiveSetupRunner,
|
|
175
194
|
// executeRunAgentCommand emits messages (before launch) through this sink.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"RunAgentCommand.js","sourceRoot":"","sources":["../../../src/cli/commands/RunAgentCommand.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;
|
|
1
|
+
{"version":3,"file":"RunAgentCommand.js","sourceRoot":"","sources":["../../../src/cli/commands/RunAgentCommand.ts"],"names":[],"mappings":"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"}
|
|
@@ -1,3 +1,7 @@
|
|
|
1
|
+
// Projects a harness-neutral CompositionPlan to a native pi or Claude Code launch.
|
|
2
|
+
import { readFileSync, writeFileSync } from 'node:fs';
|
|
3
|
+
import { join } from 'node:path';
|
|
4
|
+
import { PI_SESSION_DIRECTORY_ENV } from '../agents/PiSessionDirectory.js';
|
|
1
5
|
import { materializeComposition, materializeConfigurationOverlays } from './Materialize.js';
|
|
2
6
|
// Loadout elements a projection actually maps to native config. Anything else is reported
|
|
3
7
|
// unsupported so `--strict` catches silently-dropped selections. Baseline for both harnesses is
|
|
@@ -36,10 +40,41 @@ const loadoutElementsInUse = (composition) => {
|
|
|
36
40
|
return present;
|
|
37
41
|
};
|
|
38
42
|
export const unsupportedElements = (composition, input) => loadoutElementsInUse(composition).filter((element) => !supportedElements(input).includes(element));
|
|
43
|
+
/**
|
|
44
|
+
* The two harnesses take prompt documents through incompatible flags, verified against pi 0.x via
|
|
45
|
+
* `outfitter run` and Claude Code 2.1.x directly:
|
|
46
|
+
*
|
|
47
|
+
* | | pi | claude |
|
|
48
|
+
* | `--system-prompt <path>` / `--append-system-prompt <path>` | reads the file | appends the path *text* |
|
|
49
|
+
* | `--system-prompt-file` / `--append-system-prompt-file` | rejected: `Unknown option` | reads the file |
|
|
50
|
+
* | repeated append flags | accumulate | last one wins |
|
|
51
|
+
*
|
|
52
|
+
* pi therefore takes paths on the bare flags, and Claude takes the `-file` forms. Claude's are
|
|
53
|
+
* undocumented — neither appears in `claude --help` — but both apply the file's contents, while the
|
|
54
|
+
* bare flags silently append the path string and drop the document. Getting this wrong produces no
|
|
55
|
+
* error, just an agent launched without its identity.
|
|
56
|
+
*
|
|
57
|
+
* Claude also gets a single append flag over a concatenation, because repeats overwrite.
|
|
58
|
+
*/
|
|
59
|
+
const promptPathArg = (harness, flag) => harness === 'pi' ? `--${flag}` : `--${flag}-file`;
|
|
60
|
+
const appendPromptArgs = (harness, rootDirectory, paths) => {
|
|
61
|
+
/* v8 ignore next 2 -- unreachable through composition, which always contributes the agent body;
|
|
62
|
+
kept because projectComposition is exported and an empty list must not name an empty file. */
|
|
63
|
+
if (paths.length === 0)
|
|
64
|
+
return [];
|
|
65
|
+
if (harness === 'pi')
|
|
66
|
+
return paths.flatMap((path) => ['--append-system-prompt', path]);
|
|
67
|
+
const combinedPath = join(rootDirectory, 'append-system-prompt.md');
|
|
68
|
+
// A blank line between documents: one newline would let a document that ends mid-sentence merge
|
|
69
|
+
// into the next one's opening paragraph, or turn it into a setext heading.
|
|
70
|
+
const documents = paths.map((path) => readFileSync(path, 'utf8').replace(/\n*$/, '\n'));
|
|
71
|
+
writeFileSync(combinedPath, documents.join('\n'));
|
|
72
|
+
return [promptPathArg(harness, 'append-system-prompt'), combinedPath];
|
|
73
|
+
};
|
|
39
74
|
const promptArgs = (composition, input, systemPromptPath, appendPromptPaths) => [
|
|
40
|
-
'
|
|
75
|
+
promptPathArg(input.harness, 'system-prompt'),
|
|
41
76
|
systemPromptPath,
|
|
42
|
-
...
|
|
77
|
+
...appendPromptArgs(input.harness, input.rootDirectory, appendPromptPaths),
|
|
43
78
|
...(input.harness === 'pi' && composition.identity.promptTemplate !== undefined
|
|
44
79
|
? ['--prompt-template', `${input.rootDirectory}/prompt-template.md`]
|
|
45
80
|
: []),
|
|
@@ -67,7 +102,15 @@ const buildLaunchPlan = (composition, input, systemPromptPath, appendPromptPaths
|
|
|
67
102
|
...modelArgs(composition, input.harness),
|
|
68
103
|
...(input.passThroughArgs ?? []),
|
|
69
104
|
],
|
|
70
|
-
|
|
105
|
+
// The projection root is deleted after the run, so pi's default session store (a subdirectory
|
|
106
|
+
// of PI_CODING_AGENT_DIR) would take every transcript with it. A resolved session directory
|
|
107
|
+
// moves the store somewhere durable so `--continue`/`--resume` still find the last conversation.
|
|
108
|
+
env: isPi
|
|
109
|
+
? {
|
|
110
|
+
PI_CODING_AGENT_DIR: input.rootDirectory,
|
|
111
|
+
...(input.sessionDirectory === undefined ? {} : { [PI_SESSION_DIRECTORY_ENV]: input.sessionDirectory }),
|
|
112
|
+
}
|
|
113
|
+
: { CLAUDE_CONFIG_DIR: input.rootDirectory },
|
|
71
114
|
};
|
|
72
115
|
};
|
|
73
116
|
/** Materializes the composition into the runtime root and builds the harness launch plan. */
|
|
@@ -76,7 +119,11 @@ export const projectComposition = (composition, input) => {
|
|
|
76
119
|
materializeConfigurationOverlays(input.configurationOverlayDirectories ?? [], input.rootDirectory);
|
|
77
120
|
}
|
|
78
121
|
const materialized = materializeComposition(composition, input.rootDirectory);
|
|
79
|
-
|
|
122
|
+
// Caller documents follow the composition's own, so a persona is read against the agent it adopts.
|
|
123
|
+
const launch = buildLaunchPlan(composition, input, materialized.systemPromptPath, [
|
|
124
|
+
...materialized.appendPromptPaths,
|
|
125
|
+
...(input.appendPromptPaths ?? []),
|
|
126
|
+
]);
|
|
80
127
|
const unsupported = [
|
|
81
128
|
...unsupportedElements(composition, input),
|
|
82
129
|
...materialized.skippedSkills.map((slug) => `skill:${slug} (escaping symlink)`),
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ProjectHarness.js","sourceRoot":"","sources":["../../src/projection/ProjectHarness.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"ProjectHarness.js","sourceRoot":"","sources":["../../src/projection/ProjectHarness.ts"],"names":[],"mappings":"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"}
|
|
@@ -15,7 +15,15 @@ export interface ProjectionInput {
|
|
|
15
15
|
readonly harness: Harness;
|
|
16
16
|
readonly rootDirectory: string;
|
|
17
17
|
readonly homeDirectory: string;
|
|
18
|
+
/** Durable session store for the run (pi only); omitted to leave the harness default in place. */
|
|
19
|
+
readonly sessionDirectory?: string;
|
|
18
20
|
readonly passThroughArgs?: readonly string[];
|
|
21
|
+
/**
|
|
22
|
+
* Caller-supplied documents appended to the system prompt after the composition's own, in the
|
|
23
|
+
* order given — typically a persona, by absolute path from outside the projection root. Projected
|
|
24
|
+
* per harness, since pi and claude take append-prompt documents through incompatible flags.
|
|
25
|
+
*/
|
|
26
|
+
readonly appendPromptPaths?: readonly string[];
|
|
19
27
|
/** Local pi extension install directories to load with `--extension` (pi only). */
|
|
20
28
|
readonly extensionLoadDirs?: readonly string[];
|
|
21
29
|
/** Harness-native configuration directories, highest precedence first, overlaid into the root. */
|
|
@@ -49,7 +49,7 @@ The protocol resources Outfitter resolves and composes:
|
|
|
49
49
|
Three related terms, none of which is a settings key or a separate file format:
|
|
50
50
|
|
|
51
51
|
- A **[profile](./profiles.md)** is just an agent and its loadout. "The engineer profile" is the `engineer` agent with everything it composes. There is no `profile.yml` and no `profiles:` map — the loadout lives on the agent.
|
|
52
|
-
- A **[persona](./personas.md)** is a _convention_, not a resource: one portable, committed Markdown document per persona — for
|
|
52
|
+
- A **[persona](./personas.md)** is a _convention_, not a resource: one portable, committed Markdown document per persona — `docs/personas/platform-lead.md` for a project's own readers, or `~/.agents/personas/platform-lead.md` for a reader who outlives one repository — appended at launch to a shared review agent, or pasted into any tool as stakeholder context. Swapping the file swaps the persona.
|
|
53
53
|
- A **[subagent](./subagents.md)** is an agent projected into the harness's native delegation mechanism, selected in another agent's `subagents` loadout. A leader agent delegates to local coding-harness subagents or to issue- and action-backed subagents.
|
|
54
54
|
|
|
55
55
|
The same agent definition can be run directly or selected as a subagent elsewhere; its loadout decides what it composes.
|
|
@@ -13,30 +13,56 @@ A persona file is plain Markdown with no frontmatter and no schema:
|
|
|
13
13
|
- First-person prose: an unheaded opening paragraph, then the recommended sections `## My work and context`, `## What I need`, `## How I decide`, and `## How I communicate`. Sections may be renamed or combined; connected prose beats bullet stacks.
|
|
14
14
|
- Everything the persona knows — role, goals, constraints, decision signals, voice — is ordinary Markdown.
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
The authoring template and completed reference personas ship in the community catalog's [`persona-authoring`](https://github.com/ai-outfitter/community-profiles/tree/main/skills/persona-authoring) skill.
|
|
17
|
+
|
|
18
|
+
## Where personas live
|
|
19
|
+
|
|
20
|
+
A persona file lives in normal documentation, deliberately outside `.agents/`, in one of two tiers:
|
|
17
21
|
|
|
18
22
|
```text
|
|
19
|
-
docs/personas/
|
|
23
|
+
docs/personas/ # project tier — readers of this project
|
|
20
24
|
platform-lead.md
|
|
25
|
+
~/.agents/personas/ # cross-project tier — readers who outlive one repository
|
|
21
26
|
founder-operator.md
|
|
22
27
|
```
|
|
23
28
|
|
|
24
|
-
|
|
29
|
+
Use the **project tier** when the persona only makes sense next to the work it describes. Use the **cross-project tier** when the reader exists independently of any single repository — the file is then reachable from any working directory, including `~`. Filenames are lowercase and hyphenated and name the role rather than the person.
|
|
30
|
+
|
|
31
|
+
Neither tier is a resource Outfitter resolves; both are ordinary directories of Markdown. A persona is project steering context rather than agent configuration, which is why `outfitter dump` does not carry it. The `persona-review` launcher searches the project tier before the cross-project one, so `--persona platform-lead` picks up a project override of a shared role without renaming anything.
|
|
25
32
|
|
|
26
33
|
## Three ways to consume the same file
|
|
27
34
|
|
|
28
|
-
- **Appended at launch**: `outfitter run persona-reviewer --
|
|
35
|
+
- **Appended at launch**: `outfitter run persona-reviewer --append-prompt docs/personas/platform-lead.md -- …` — the direct run is the underlying interface, and the reviewer adopts the file as its identity for that session only. Pass `--append-prompt` rather than spelling the harness flag yourself after `--`: pi and Claude Code take append-prompt documents through different flags, so a hand-written passthrough only works on the harness it was written for, and fails silently on the other. An agent using the [`persona-review`](https://github.com/ai-outfitter/community-profiles/tree/main/skills/persona-review) skill can drive the same run in the background or synchronously and capture its report in a durable file. See [Persona reviews](./usecases/persona-reviews.md) for the runnable form of both.
|
|
29
36
|
- **Pasted into a web agent**: upload or paste the file unchanged into claude.ai project knowledge or a ChatGPT project as stakeholder context. Same artifact, zero conversion.
|
|
30
37
|
- **Ordinary reading context**: any agent doing product planning, research, or writing can read the file to know who the work is for.
|
|
31
38
|
|
|
39
|
+
## When one file is not enough
|
|
40
|
+
|
|
41
|
+
Start with one file. Reach for a second only when part of an identity varies independently and would otherwise be copied into every persona that shares it — most often an **organization**: sector, scale, regulatory exposure, how the business weighs risk against speed. Three organizations against four roles is seven documents rather than twelve.
|
|
42
|
+
|
|
43
|
+
```sh
|
|
44
|
+
outfitter run persona-reviewer \
|
|
45
|
+
--append-prompt docs/personas/org.enterprise-insurance.md \
|
|
46
|
+
--append-prompt docs/personas/platform-lead.md \
|
|
47
|
+
-- --print "Review the onboarding flow. @README.md"
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Order is meaning: earlier documents establish the context later ones are read against, so organization comes before role, and a named individual comes last. A role document written for composition must not name a sector or an employer — that is exactly what lets it read correctly under any organization.
|
|
51
|
+
|
|
52
|
+
Each file is still ordinary Markdown that reads on its own, names no other file, and leaves no placeholder for one. Splitting for any other reason — to store a schema in filenames, to make files shorter, to mirror a template — is the failure mode the next section describes, and it remains the wrong move.
|
|
53
|
+
|
|
54
|
+
Portability survives intact. Every document uploads unchanged into claude.ai project knowledge or a ChatGPT project; when an identity spans several, upload them in the same order, or `cat org.md role.md > persona.md` and upload the one file. The claim was never _one artifact_ — it is _no conversion step_, and `cat` is not a conversion step.
|
|
55
|
+
|
|
32
56
|
## Why a convention, not a key
|
|
33
57
|
|
|
34
|
-
Modeling personas as their own resource —
|
|
58
|
+
Modeling personas as their own resource — a `personas:` key that Outfitter resolves, merges across layers, validates, and projects — duplicates what an agent already is and grows the surface area of the system. Naming documents at launch is not that: Outfitter resolves nothing, merges nothing, validates nothing, and `outfitter dump` still carries no persona. Order is whatever you typed on the command line, not a precedence rule the system has to define and defend.
|
|
59
|
+
|
|
60
|
+
Keeping personas as "shared agent plus committed Markdown" means a team maintains one review agent and a directory of cheap files, instead of a fleet of near-identical agents. A tenth persona is a tenth file; a second organization is one more file, not a copy of every role.
|
|
35
61
|
|
|
36
|
-
Organization research, interviews, and individual detail are **authoring inputs**, not committed schema: interview from them, keep research notes however you like, but
|
|
62
|
+
Organization research, interviews, and individual detail are **authoring inputs**, not committed schema: interview from them, keep research notes however you like, but what gets committed is Markdown a person can read. Do not invent demographics, income, or biography the research does not support, and never generate an Outfitter agent per persona.
|
|
37
63
|
|
|
38
64
|
## Status
|
|
39
65
|
|
|
40
|
-
Personas ride entirely on existing CLI behavior
|
|
66
|
+
Personas ride entirely on existing CLI behavior — `outfitter run` plus `--append-prompt`, which projects each document through whichever flag the selected harness actually reads — so no `OFTR-*` requirement covers them beyond the composition order in `OFTR-005.3.1`. The reviewer runs as the selected agent; native Pi subagent projection is not a prerequisite. An `.agents`-native persona form (a protocol resource, or a settings layer pointing at persona documents) is a separate, deferred design; the portable file must never depend on it.
|
|
41
67
|
|
|
42
68
|
See [Persona reviews](./usecases/persona-reviews.md) for the worked author → run → paste-anywhere story, and the community catalog's [persona boundary doc](https://github.com/ai-outfitter/community-profiles/blob/main/docs/persona-review.md) for the setup and runtime responsibility split.
|
|
@@ -152,7 +152,7 @@ state_persistence:
|
|
|
152
152
|
trust.json: symlink # Pi trust decisions.
|
|
153
153
|
plugins/: symlink # Pi plugins.
|
|
154
154
|
cache/: symlink # Pi cache data.
|
|
155
|
-
sessions/: symlink # Pi sessions.
|
|
155
|
+
sessions/: symlink # Pi sessions; the "Pi sessions" section covers how this works today.
|
|
156
156
|
npm/: symlink # Pi npm package installs.
|
|
157
157
|
git/: symlink # Pi git package checkouts.
|
|
158
158
|
tmp/: symlink # Pi temporary runtime tree; allowed: symlink, discard.
|
|
@@ -161,6 +161,33 @@ state_persistence:
|
|
|
161
161
|
unknown: warn # Undeclared writes; allowed: discard, warn, error, prompt.
|
|
162
162
|
```
|
|
163
163
|
|
|
164
|
+
## Pi sessions
|
|
165
|
+
|
|
166
|
+
Pi stores conversation transcripts under its agent directory, and Outfitter points `PI_CODING_AGENT_DIR` at a baked composition that is deleted when the run ends. So that sessions are not deleted with it, every Pi launch sets `PI_CODING_AGENT_SESSION_DIR` to Pi's own durable per-project session folder:
|
|
167
|
+
|
|
168
|
+
```text
|
|
169
|
+
~/.pi/agent/sessions/--<your-project-path>--/
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
This is the same folder a standalone `pi` uses in that project, so history is shared both ways and resuming works after the baked composition is gone:
|
|
173
|
+
|
|
174
|
+
```sh
|
|
175
|
+
outfitter run # first session
|
|
176
|
+
outfitter run -- --continue # picks up where the previous run left off
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
The default applies to every Pi launch, interactive or not, so `outfitter run -p '…'` in a script or CI job records a session in the same place. Nothing is copied back after the run: Pi writes straight to the durable directory.
|
|
180
|
+
|
|
181
|
+
To change or turn off session storage, pass Pi's native flags through, or set the environment variable yourself — Outfitter never overrides a session directory you have already chosen:
|
|
182
|
+
|
|
183
|
+
```sh
|
|
184
|
+
outfitter run -- --no-session # ephemeral: record nothing
|
|
185
|
+
outfitter run -- --session-dir ./.pi/sessions # keep this project's sessions in the repo
|
|
186
|
+
PI_CODING_AGENT_SESSION_DIR=/workspace/.pi/agent/sessions outfitter run
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
The last form is how a resident or in-cluster agent keeps continuity across restarts: point the variable at a persistent volume.
|
|
190
|
+
|
|
164
191
|
## Claude Code state paths
|
|
165
192
|
|
|
166
193
|
The Claude Code adapter declares these paths:
|
|
@@ -76,6 +76,8 @@ docs/personas/
|
|
|
76
76
|
founder-operator.md
|
|
77
77
|
```
|
|
78
78
|
|
|
79
|
+
A persona whose reader exists independently of any one repository goes in `~/.agents/personas/` instead, where every working directory can reach it. See [Where personas live](../personas.md#where-personas-live).
|
|
80
|
+
|
|
79
81
|
Prefer generic role archetypes over named individuals. Research and interviews are authoring inputs; commit only the self-contained file, and invent nothing the research does not support.
|
|
80
82
|
|
|
81
83
|
## Run it under Outfitter
|
|
@@ -84,13 +86,12 @@ After `outfitter setup`, launch the shared reviewer directly with the persona ap
|
|
|
84
86
|
|
|
85
87
|
```sh
|
|
86
88
|
mkdir -p docs/persona-reviews
|
|
87
|
-
outfitter run persona-reviewer -- \
|
|
88
|
-
--append-system-prompt docs/personas/platform-lead.md \
|
|
89
|
+
outfitter run persona-reviewer --append-prompt docs/personas/platform-lead.md -- \
|
|
89
90
|
--print "Review the onboarding flow and write the report. @README.md" \
|
|
90
91
|
> docs/persona-reviews/platform-lead-onboarding.md
|
|
91
92
|
```
|
|
92
93
|
|
|
93
|
-
This is the portable interface: it works from the project containing the persona
|
|
94
|
+
This is the portable interface: it works from the project containing the persona, does not assume a particular catalog checkout path, and does not assume a harness — `--append-prompt` projects the document through whichever flag pi or Claude Code actually reads. Repeat it to compose an identity from several documents; see [When one file is not enough](../personas.md#when-one-file-is-not-enough). One shared agent adopts the file as its identity for that session only and writes a first-person, sourced report — evidence cited to the exact page or UI moment, assumptions labeled. The reviewer inherits the caller's configured model; reviews benefit from a strong reasoning model.
|
|
94
95
|
|
|
95
96
|
### Optional orchestration with the skill
|
|
96
97
|
|
|
@@ -98,12 +99,12 @@ Use the [`persona-review`](https://github.com/ai-outfitter/community-profiles/tr
|
|
|
98
99
|
|
|
99
100
|
```sh
|
|
100
101
|
bash skills/persona-review/scripts/persona-review.sh \
|
|
101
|
-
--persona
|
|
102
|
+
--persona platform-lead \
|
|
102
103
|
--report docs/persona-reviews/platform-lead-onboarding.md \
|
|
103
104
|
-- --print "Review the onboarding flow and write the report. @README.md"
|
|
104
105
|
```
|
|
105
106
|
|
|
106
|
-
The reviewer runs directly as the selected agent. This journey does not require Pi's native subagent projection.
|
|
107
|
+
A bare `--persona` name resolves against `docs/personas/`, then `.agents/personas/`, then `~/.agents/personas/`, so the same command works whether the persona is project-local or cross-project; pass a path to name a file directly. The reviewer runs directly as the selected agent. This journey does not require Pi's native subagent projection.
|
|
107
108
|
|
|
108
109
|
## Take the same file to the web
|
|
109
110
|
|
package/package.json
CHANGED