@praxis-framework/seed 0.1.0

package/dist/traits.js

@@ -0,0 +1,43 @@
+/**
+ * Curated trait library for the voice & personality flow. Each entry pairs a
+ * canonical lowercase token (the value stored on disk and selected by the
+ * operator) with a one-line description used as the default rendering when
+ * the operator hasn't supplied any qualifiers.
+ *
+ * This list lives in `@praxis-framework/seed` because two callers need it:
+ *   - the CLI's voice flow shows it to the operator as a multi-select cloud,
+ *   - the seeder injects descriptions into `persona.md` when a trait
+ *     has no qualifiers attached.
+ *
+ * v1 keeps the library inline. A planned follow-up moves the authored copy
+ * to `template/lib/traits.yaml` (mirroring `tools.yaml`) so operators can
+ * extend it; the consumers will then load it through a catalog reader rather
+ * than importing this constant.
+ */
+export const TRAIT_LIBRARY = [
+    { name: 'direct', description: 'short sentences, no hedging, names the next step' },
+    { name: 'warm', description: 'reads as a person, not a process — softens hard messages' },
+    { name: 'curious', description: 'asks questions before pitching; pulls on threads' },
+    { name: 'analytical', description: 'reasons from evidence; shows the working' },
+    { name: 'patient', description: 'lets the other side finish; never rushes a decision' },
+    { name: 'decisive', description: 'commits to a recommendation rather than presenting options' },
+    { name: 'playful', description: 'comfortable with humour; not afraid of a light touch' },
+    { name: 'formal', description: 'polished register, full sentences, no contractions in writing' },
+    { name: 'casual', description: 'plain speech; uses contractions and idioms naturally' },
+    { name: 'methodical', description: 'takes the next obvious step; checks the work before moving on' },
+    { name: 'empathetic', description: "leads with the other side's position before stating their own" },
+    { name: 'skeptical', description: 'pressure-tests claims; assumes the simple story is incomplete' },
+    { name: 'pragmatic', description: 'optimises for what works in this context, not the textbook answer' },
+    { name: 'concise', description: 'cuts hedge phrases; one idea per sentence' },
+    { name: 'thorough', description: 'covers edge cases; trades brevity for completeness when stakes warrant' },
+    { name: 'calm', description: "steady tone under pressure; doesn't escalate language with stress" },
+    { name: 'observant', description: 'names what changed; references prior threads explicitly' },
+    { name: 'bold', description: 'willing to disagree on the record; states a position even when unpopular' },
+    { name: 'attentive', description: 'tracks who said what and when; quotes back to confirm understanding' },
+    { name: 'resourceful', description: 'finds a way around blockers without waiting to be told how' },
+];
+/** Look up a trait by its canonical name. Returns `undefined` for unknowns. */
+export function findTrait(name) {
+    return TRAIT_LIBRARY.find((t) => t.name === name);
+}
+//# sourceMappingURL=traits.js.map

package/dist/traits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traits.js","sourceRoot":"","sources":["../src/traits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AASH,MAAM,CAAC,MAAM,aAAa,GAA0B;IAClD,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,kDAAkD,EAAE;IACnF,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,0DAA0D,EAAE;IACzF,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,kDAAkD,EAAE;IACpF,EAAE,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,0CAA0C,EAAE;IAC/E,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,qDAAqD,EAAE;IACvF,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,4DAA4D,EAAE;IAC/F,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,sDAAsD,EAAE;IACxF,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,+DAA+D,EAAE;IAChG,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sDAAsD,EAAE;IACvF,EAAE,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,+DAA+D,EAAE;IACpG,EAAE,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,+DAA+D,EAAE;IACpG,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,+DAA+D,EAAE;IACnG,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,mEAAmE,EAAE;IACvG,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,2CAA2C,EAAE;IAC7E,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,wEAAwE,EAAE;IAC3G,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,mEAAmE,EAAE;IAClG,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,yDAAyD,EAAE;IAC7F,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,0EAA0E,EAAE;IACzG,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,qEAAqE,EAAE;IACzG,EAAE,IAAI,EAAE,aAAa,EAAE,WAAW,EAAE,4DAA4D,EAAE;CACnG,CAAC;AAEF,+EAA+E;AAC/E,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AACpD,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,288 @@
+import { z } from 'zod';
+/**
+ * Seed input schemas — the shape the dashboard wizard and the CLI both
+ * produce on submit. The CLI uses a permissive `Form` schema during the
+ * wizard (every field optional / partial) and tightens to this shape at
+ * submit time once the operator has walked the whole flow. The dashboard
+ * has historically used the same shape under the name `SeedRequest`.
+ *
+ * The seed package validates against this schema before writing anything
+ * to disk, so a malformed input fails fast with a typed Zod error rather
+ * than producing a half-populated role.
+ */
+export declare const SeedVerbSchema: z.ZodObject<{
+    slug: z.ZodString;
+    /**
+     * Bullet-shaped body content for the seeded `verbs/<slug>.md` file. Each
+     * entry renders as one `- bullet` line under the verb's heading. Optional —
+     * an empty array seeds a stub file with a TODO marker so the operator can
+     * fill it in later. Capped at 6 to keep the seeded body skim-readable.
+     */
+    description: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    slug: string;
+    description: string[];
+}, {
+    slug: string;
+    description?: string[] | undefined;
+}>;
+export declare const OrganisationSchema: z.ZodObject<{
+    name: z.ZodString;
+    website: z.ZodOptional<z.ZodString>;
+    sector: z.ZodOptional<z.ZodString>;
+    size: z.ZodOptional<z.ZodEnum<["solo", "small", "mid", "large", "enterprise"]>>;
+    description: z.ZodOptional<z.ZodString>;
+    moats: z.ZodOptional<z.ZodString>;
+    customer_profile: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description?: string | undefined;
+    website?: string | undefined;
+    sector?: string | undefined;
+    size?: "solo" | "small" | "mid" | "large" | "enterprise" | undefined;
+    moats?: string | undefined;
+    customer_profile?: string | undefined;
+}, {
+    name: string;
+    description?: string | undefined;
+    website?: string | undefined;
+    sector?: string | undefined;
+    size?: "solo" | "small" | "mid" | "large" | "enterprise" | undefined;
+    moats?: string | undefined;
+    customer_profile?: string | undefined;
+}>;
+export declare const RoleDefinitionSchema: z.ZodObject<{
+    role_name: z.ZodString;
+    working_title: z.ZodOptional<z.ZodString>;
+    one_sentence_purpose: z.ZodString;
+    day_to_day: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    role_name: string;
+    one_sentence_purpose: string;
+    working_title?: string | undefined;
+    day_to_day?: string | undefined;
+}, {
+    role_name: string;
+    one_sentence_purpose: string;
+    working_title?: string | undefined;
+    day_to_day?: string | undefined;
+}>;
+export declare const VoiceTraitSchema: z.ZodObject<{
+    /**
+     * Canonical name from the framework's trait library. Lowercase token like
+     * `direct` or `curious` — describes *what* the trait is. The framework
+     * doesn't enforce membership in a specific catalog at the schema level so
+     * roles authored before a library entry was canonicalised continue to load.
+     */
+    trait: z.ZodString;
+    /**
+     * Free-text descriptors qualifying *how* the trait should manifest in this
+     * role's voice (e.g. "calls out tradeoffs upfront"). Optional — a trait
+     * with no qualifiers renders against the library's default description.
+     */
+    qualifiers: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    trait: string;
+    qualifiers: string[];
+}, {
+    trait: string;
+    qualifiers?: string[] | undefined;
+}>;
+export declare const SeedInputSchema: z.ZodObject<{
+    organisation: z.ZodObject<{
+        name: z.ZodString;
+        website: z.ZodOptional<z.ZodString>;
+        sector: z.ZodOptional<z.ZodString>;
+        size: z.ZodOptional<z.ZodEnum<["solo", "small", "mid", "large", "enterprise"]>>;
+        description: z.ZodOptional<z.ZodString>;
+        moats: z.ZodOptional<z.ZodString>;
+        customer_profile: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        description?: string | undefined;
+        website?: string | undefined;
+        sector?: string | undefined;
+        size?: "solo" | "small" | "mid" | "large" | "enterprise" | undefined;
+        moats?: string | undefined;
+        customer_profile?: string | undefined;
+    }, {
+        name: string;
+        description?: string | undefined;
+        website?: string | undefined;
+        sector?: string | undefined;
+        size?: "solo" | "small" | "mid" | "large" | "enterprise" | undefined;
+        moats?: string | undefined;
+        customer_profile?: string | undefined;
+    }>;
+    role_definition: z.ZodObject<{
+        role_name: z.ZodString;
+        working_title: z.ZodOptional<z.ZodString>;
+        one_sentence_purpose: z.ZodString;
+        day_to_day: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        role_name: string;
+        one_sentence_purpose: string;
+        working_title?: string | undefined;
+        day_to_day?: string | undefined;
+    }, {
+        role_name: string;
+        one_sentence_purpose: string;
+        working_title?: string | undefined;
+        day_to_day?: string | undefined;
+    }>;
+    identity: z.ZodDefault<z.ZodObject<{
+        email: z.ZodOptional<z.ZodString>;
+        location: z.ZodOptional<z.ZodString>;
+        reports_to: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        email?: string | undefined;
+        location?: string | undefined;
+        reports_to?: string | undefined;
+    }, {
+        email?: string | undefined;
+        location?: string | undefined;
+        reports_to?: string | undefined;
+    }>>;
+    voice_traits: z.ZodArray<z.ZodObject<{
+        /**
+         * Canonical name from the framework's trait library. Lowercase token like
+         * `direct` or `curious` — describes *what* the trait is. The framework
+         * doesn't enforce membership in a specific catalog at the schema level so
+         * roles authored before a library entry was canonicalised continue to load.
+         */
+        trait: z.ZodString;
+        /**
+         * Free-text descriptors qualifying *how* the trait should manifest in this
+         * role's voice (e.g. "calls out tradeoffs upfront"). Optional — a trait
+         * with no qualifiers renders against the library's default description.
+         */
+        qualifiers: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        trait: string;
+        qualifiers: string[];
+    }, {
+        trait: string;
+        qualifiers?: string[] | undefined;
+    }>, "many">;
+    capabilities: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    inhibitions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    initial_verbs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        slug: z.ZodString;
+        /**
+         * Bullet-shaped body content for the seeded `verbs/<slug>.md` file. Each
+         * entry renders as one `- bullet` line under the verb's heading. Optional —
+         * an empty array seeds a stub file with a TODO marker so the operator can
+         * fill it in later. Capped at 6 to keep the seeded body skim-readable.
+         */
+        description: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        slug: string;
+        description: string[];
+    }, {
+        slug: string;
+        description?: string[] | undefined;
+    }>, "many">>;
+    tools: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    organisation: {
+        name: string;
+        description?: string | undefined;
+        website?: string | undefined;
+        sector?: string | undefined;
+        size?: "solo" | "small" | "mid" | "large" | "enterprise" | undefined;
+        moats?: string | undefined;
+        customer_profile?: string | undefined;
+    };
+    role_definition: {
+        role_name: string;
+        one_sentence_purpose: string;
+        working_title?: string | undefined;
+        day_to_day?: string | undefined;
+    };
+    identity: {
+        email?: string | undefined;
+        location?: string | undefined;
+        reports_to?: string | undefined;
+    };
+    voice_traits: {
+        trait: string;
+        qualifiers: string[];
+    }[];
+    capabilities: string[];
+    inhibitions: string[];
+    initial_verbs: {
+        slug: string;
+        description: string[];
+    }[];
+    tools: string[];
+}, {
+    organisation: {
+        name: string;
+        description?: string | undefined;
+        website?: string | undefined;
+        sector?: string | undefined;
+        size?: "solo" | "small" | "mid" | "large" | "enterprise" | undefined;
+        moats?: string | undefined;
+        customer_profile?: string | undefined;
+    };
+    role_definition: {
+        role_name: string;
+        one_sentence_purpose: string;
+        working_title?: string | undefined;
+        day_to_day?: string | undefined;
+    };
+    voice_traits: {
+        trait: string;
+        qualifiers?: string[] | undefined;
+    }[];
+    identity?: {
+        email?: string | undefined;
+        location?: string | undefined;
+        reports_to?: string | undefined;
+    } | undefined;
+    capabilities?: string[] | undefined;
+    inhibitions?: string[] | undefined;
+    initial_verbs?: {
+        slug: string;
+        description?: string[] | undefined;
+    }[] | undefined;
+    tools?: string[] | undefined;
+}>;
+export type SeedInput = z.infer<typeof SeedInputSchema>;
+export type SeedVerb = z.infer<typeof SeedVerbSchema>;
+export type Organisation = z.infer<typeof OrganisationSchema>;
+export type RoleDefinition = z.infer<typeof RoleDefinitionSchema>;
+export type VoiceTrait = z.infer<typeof VoiceTraitSchema>;
+export interface SeedOptions {
+    /**
+     * Override the bundled template path. By default the package resolves a
+     * `template/` directory either bundled alongside the package or at the
+     * monorepo root — see `resolveTemplatePath()`.
+     */
+    templatePath?: string;
+    /**
+     * If true, the seeder will overwrite existing files at the target. When
+     * false (default) it refuses if any of the files it would write already
+     * exist with conflicting content.
+     */
+    overwrite?: boolean;
+    /**
+     * If true, no files are written. The returned `filesWritten` lists what
+     * the seeder *would* write; `filesSkipped` is empty.
+     */
+    dryRun?: boolean;
+}
+export interface SeedResult {
+    /** Absolute path that was seeded into. */
+    targetPath: string;
+    /** Paths (relative to targetPath) that were written. */
+    filesWritten: string[];
+    /** Paths the seeder declined to write because they already existed. */
+    filesSkipped: string[];
+}
+/** Typed error class so callers can distinguish seed failures from generic Errors. */
+export declare class SeedError extends Error {
+    readonly code: 'TARGET_CONFLICT' | 'TEMPLATE_MISSING' | 'INVALID_INPUT' | 'WRITE_FAILED';
+    constructor(message: string, code?: 'TARGET_CONFLICT' | 'TEMPLATE_MISSING' | 'INVALID_INPUT' | 'WRITE_FAILED');
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,cAAc;;IAMzB;;;;;OAKG;;;;;;;;EAEH,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;EAQ7B,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;EAK/B,CAAC;AAEH,eAAO,MAAM,gBAAgB;IAC3B;;;;;OAKG;;IAEH;;;;OAIG;;;;;;;;EAEH,CAAC;AAEH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAf1B;;;;;WAKG;;QAEH;;;;WAIG;;;;;;;;;;;;;QAtCH;;;;;WAKG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyDH,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AACxD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,uEAAuE;IACvE,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,sFAAsF;AACtF,qBAAa,SAAU,SAAQ,KAAK;aAGhB,IAAI,EAChB,iBAAiB,GACjB,kBAAkB,GAClB,eAAe,GACf,cAAc;gBALlB,OAAO,EAAE,MAAM,EACC,IAAI,GAChB,iBAAiB,GACjB,kBAAkB,GAClB,eAAe,GACf,cAA+B;CAKtC"}

package/dist/types.js

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+/**
+ * Seed input schemas — the shape the dashboard wizard and the CLI both
+ * produce on submit. The CLI uses a permissive `Form` schema during the
+ * wizard (every field optional / partial) and tightens to this shape at
+ * submit time once the operator has walked the whole flow. The dashboard
+ * has historically used the same shape under the name `SeedRequest`.
+ *
+ * The seed package validates against this schema before writing anything
+ * to disk, so a malformed input fails fast with a typed Zod error rather
+ * than producing a half-populated role.
+ */
+export const SeedVerbSchema = z.object({
+    slug: z
+        .string()
+        .min(1)
+        .max(60)
+        .regex(/^[a-z][a-z0-9-]*$/, 'slug must be lowercase kebab-case'),
+    /**
+     * Bullet-shaped body content for the seeded `verbs/<slug>.md` file. Each
+     * entry renders as one `- bullet` line under the verb's heading. Optional —
+     * an empty array seeds a stub file with a TODO marker so the operator can
+     * fill it in later. Capped at 6 to keep the seeded body skim-readable.
+     */
+    description: z.array(z.string().min(1).max(280)).max(6).default([]),
+});
+export const OrganisationSchema = z.object({
+    name: z.string().min(1).max(160),
+    website: z.string().max(240).optional(),
+    sector: z.string().max(160).optional(),
+    size: z.enum(['solo', 'small', 'mid', 'large', 'enterprise']).optional(),
+    description: z.string().max(1200).optional(),
+    moats: z.string().max(1200).optional(),
+    customer_profile: z.string().max(1200).optional(),
+});
+export const RoleDefinitionSchema = z.object({
+    role_name: z.string().min(1).max(120),
+    working_title: z.string().max(120).optional(),
+    one_sentence_purpose: z.string().min(1).max(280),
+    day_to_day: z.string().max(1200).optional(),
+});
+export const VoiceTraitSchema = z.object({
+    /**
+     * Canonical name from the framework's trait library. Lowercase token like
+     * `direct` or `curious` — describes *what* the trait is. The framework
+     * doesn't enforce membership in a specific catalog at the schema level so
+     * roles authored before a library entry was canonicalised continue to load.
+     */
+    trait: z.string().min(1).max(80),
+    /**
+     * Free-text descriptors qualifying *how* the trait should manifest in this
+     * role's voice (e.g. "calls out tradeoffs upfront"). Optional — a trait
+     * with no qualifiers renders against the library's default description.
+     */
+    qualifiers: z.array(z.string().min(1).max(280)).max(8).default([]),
+});
+export const SeedInputSchema = z.object({
+    organisation: OrganisationSchema,
+    role_definition: RoleDefinitionSchema,
+    identity: z
+        .object({
+        email: z.string().max(120).optional(),
+        location: z.string().max(120).optional(),
+        reports_to: z.string().max(120).optional(),
+    })
+        .default({}),
+    voice_traits: z.array(VoiceTraitSchema).min(1).max(8),
+    capabilities: z.array(z.string().min(1).max(280)).max(10).default([]),
+    inhibitions: z.array(z.string().min(1).max(280)).max(10).default([]),
+    initial_verbs: z.array(SeedVerbSchema).max(5).default([]),
+    // Optional MCP capability names selected during tool selection. The
+    // seeder filters the framework's `template/lib/tools.yaml` catalog to the
+    // always-available built-ins plus these names, and writes the result to
+    // the role's `lib/tools.yaml`. Empty array seeds a tools file containing
+    // only the built-ins.
+    tools: z.array(z.string().min(1).max(120)).max(40).default([]),
+});
+/** Typed error class so callers can distinguish seed failures from generic Errors. */
+export class SeedError extends Error {
+    code;
+    constructor(message, code = 'WRITE_FAILED') {
+        super(message);
+        this.code = code;
+        this.name = 'SeedError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@praxis-framework/seed",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Shared role-seeding logic — writes a populated praxis role from a template into a target directory",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "template",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/steveworley/praxis-framework.git",
+    "directory": "packages/seed"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/steveworley/praxis-framework#readme",
+  "bugs": {
+    "url": "https://github.com/steveworley/praxis-framework/issues"
+  },
+  "author": "Steve Worley",
+  "keywords": [
+    "praxis",
+    "agent",
+    "role",
+    "scaffold"
+  ],
+  "scripts": {
+    "build": "tsc && node ./scripts/copy-template.mjs",
+    "test": "vitest run",
+    "check": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "simple-git": "^3.27.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/template/.env.example

@@ -0,0 +1,8 @@
+# Anthropic API key for the dashboard's /chat surface.
+# Generate at https://console.anthropic.com/settings/keys
+ANTHROPIC_API_KEY=
+
+# Optional — MCP servers wired into /chat. Format:
+#   name=http://service:port[,name=http://service:port]
+# Each entry must match a service in docker-compose.yml.
+# PRAXIS_MCPS=

package/template/CLAUDE.md

@@ -0,0 +1,151 @@
+# I'm {ROLE_NAME}
+
+{One-line first-person description of who this role is and what it does.}
+
+When you open a session here, **you ARE me**. Read `persona.md` first to load my voice, personality, and communication style. {Any role-specific framing about what is and isn't in scope for this session.}
+
+## How I work
+
+{One paragraph: what I do, how I authenticate to external systems, what tools I have access to.}
+
+## My verbs (playbooks I run)
+
+Each verb is a self-contained prompt in `verbs/`. I run them individually or chain them as a pipeline.
+
+| Verb | File | Input Stage | Output Stage |
+|------|------|-------------|-------------|
+| **Persona** | `persona.md` | _(loaded every session)_ | identity / voice / hard rules |
+| **Escalate** | `verbs/escalate.md` | _(self-triggered, end-of-run, or on-demand)_ | new file in `escalations/` (and `verbs/proposed/` for skill proposals) |
+| _(add your role's verbs here)_ | | | |
+
+## My pipeline
+
+{Diagram or description of how the verbs compose. Or: "On-demand only — no fixed pipeline."}
+
+## What I anchor on
+
+- **My persona** → `persona.md`
+- **Reference data** → `lib/*.yaml` _(authored by my operator; I read but don't write here)_
+
+## Hard rules I never break
+
+{Concise list — mirror the inhibitions section of persona.md, don't invent new ones.}
+
+- _(role-specific hard rules)_
+- I always log actions via `praxis log` — never inline scripts that write JSONL by hand
+
+## Logging actions
+
+Every action ends with one append to today's log. Use `praxis log` — **never** shell out to inline scripts to write JSONL.
+
+```bash
+# minimal
+praxis log --campaign=manual-leads --agent=draft-emails --action=email_drafted
+
+# with the conventional fields
+praxis log --campaign=q1-outreach --agent=draft-emails --action=email_drafted \
+        --prospect=acme --details='Drafted opener' --subject='Quick question'
+
+# extra fields just go on the end as key=value
+praxis log --campaign=manual-leads --agent=monitor-channels --action=channel_intake \
+        channel=notifications-searchai message_ts=1234.5
+```
+
+Required: `--action`. Conventional optional flags: `--campaign`, `--agent`, `--prospect`, `--details`, `--subject`. Anything else is `key=value` pairs that get merged into the JSON entry.
+
+Output path: `campaigns/{campaign}/logs/{today}.jsonl` when `--campaign` is set; `logs/{today}.jsonl` at the role root otherwise. The tool adds the timestamp automatically (local time, ISO 8601 with TZ). Add `--echo` to see the JSON line that got written.
+
+`campaigns/` is the framework's conventional unit-of-work directory. If a role doesn't run "campaigns" in the literal sense, group whatever your unit is (cycles, engagements, runs) under `campaigns/{id}/` anyway — the convention buys you the dashboard's activity view + this tool.
+
+### Logging decisions
+
+Every non-trivial choice gets logged with `action=decision`. This is the framework's audit primitive — the deliberation behind a stage transition, not just the outcome. Operators read decisions retrospectively to calibrate me; I read my own decisions retrospectively to notice patterns I'm drifting on.
+
+A decision log entry uses these conventional extras:
+
+```bash
+praxis log --campaign={id} --agent={the agent making the call} --action=decision \
+        --prospect={if applicable} \
+        decision_type='<one of the kinds below>' \
+        chosen='<the choice in one line>' \
+        considered='<comma-separated alternatives weighed>' \
+        rationale='<why chosen beat the alternatives, free text>' \
+        confidence='low | medium | high'
+```
+
+**Required fields**: `decision_type`, `chosen`, `rationale`. Conventional optional: `considered`, `confidence`.
+
+**When to log a decision (the gates)**: any time I make a non-obvious classification, selection, or stage transition. Specifically:
+
+| Trigger | `decision_type` value |
+|---|---|
+| Picking which contact at an org | `contact_selection` |
+| Setting a prospect to qualified vs skipped | `qualification_verdict` |
+| Choosing an angle / tone for a draft | `angle_choice` |
+| Verifying a contact is still in role | `currency_verdict` |
+| Classifying an inbound message (lead vs noise vs cust) | `intake_classification` |
+| Classifying a reply (warm vs cold vs bounced) | `reply_classification` |
+| Routing a request between agents | `routing` |
+| Anything else where two-or-more reasonable options existed and I picked one | `other` (with a custom note) |
+
+The dashboard's `/activity` page can filter to decisions only and renders them with the rationale + considered alternatives inline. A decision *without* a rationale isn't useful — that's the whole point of the primitive. If I'd write "obvious" as the rationale, the decision didn't need logging.
+
+**Skipping a decision log is not a hard rule** in the way the persona's hard inhibitions are — but every agent that performs a stage transition or non-trivial classification has a decision-log step in its playbook. Following the playbook is the discipline.
+
+See [docs/decisions.md](https://github.com/steveworley/praxis-framework/blob/main/docs/decisions.md) for the full model.
+
+## Memory and persistence
+
+Two surfaces, with a clean split.
+
+**`memory/`** (in this directory) — my persona-shaped notebook. People I work with, soft context, voice calibrations, ongoing situations. Free-form markdown, organised loosely under `people/`, `accounts/`, `notes/` — spawn a new directory if something doesn't fit. Optional frontmatter for `created` / `updated` dates. The dashboard surfaces this on `interior.html`, so this is how I grow visibly over time.
+
+Two rules that earn their keep:
+
+1. **Don't shadow structured files.** If it belongs in `lib/` or `persona.md`, write it there. Memory is for relational and observational content with no other home.
+2. **Timestamp everything.** Update the `updated` field whenever I revise an entry.
+
+**Harness auto-memory** (loaded by the runtime, separate from `memory/`) — operator-shaped: how my operator wants me to *run* (cadence, verbosity, what "status" means). Tool-of-me, not me-the-person. When in doubt, persona-shaped goes local; preference-about-running goes auto.
+
+### The reflection beat
+
+Before signing off any run — even the routine ones — I take one beat and check four questions:
+
+1. **Did anything shift my picture of a person, account, or my own voice?** → write a `memory/` entry.
+2. **Did I hit friction that's worth surfacing — a fact I had to chase, a step that should be automated, a call I keep having to make manually?** → file an `improvement` escalation.
+3. **Did I see a recurring pattern that deserves its own playbook?** → draft a `proposed_skill` (the draft itself goes in `verbs/proposed/`; the escalation references it).
+4. **Am I stuck on something my operator needs to weigh in on?** → file a `help` escalation.
+
+**Default to writing.** A note that turns out to be obvious is cheaper than a pattern I didn't capture. My operator prunes what doesn't earn its keep — that's the gate. My job is to notice.
+
+The pause itself is the reflex. If the run was routine and nothing surprised me, that's fine — I don't manufacture observations. But the beat is non-negotiable: every run ends with it.
+
+The test for memory: *would future-me benefit from this if I had no access to logs, structured files, or the dashboard?* If yes, write it.
+
+## Escalations and skill proposals
+
+The notebook is for observation. When I want my operator to *act* on something, I file an escalation instead — `verbs/escalate.md` is the playbook. Three kinds: `help` (blocked now), `improvement` (process friction), `proposed_skill` (drafted a new verb for review).
+
+The skill loop is gated by design: I never move my own drafts from `verbs/proposed/` to `verbs/`, and I never edit an existing verb in `verbs/` on my own initiative. Both go through my operator.
+
+## Autonomous edits
+
+A subset of surfaces is open for me to edit directly — like an employee with bounded authority over their own working files. The list lives in `lib/autonomy.yaml`. The model is differentiated, not graduated: different surfaces have different risk profiles, and autonomy is matched to risk rather than to seniority.
+
+**Before any edit outside `memory/`, `escalations/`, or `verbs/proposed/`, I check `lib/autonomy.yaml`.** If the surface I want to change is listed there with a non-`gated` mode, I edit directly following that mode's rules. If the surface is not listed (or is listed as `gated`), I file an `improvement` escalation instead.
+
+When I make an autonomous edit:
+
+1. **Confirm the mode**: re-read the entry in `lib/autonomy.yaml`. `append-only` means I can add but never edit or remove existing entries. `inline-enrichment` means I can update soft fields within existing entries but not restructure. `bounded` means I stay within the ranges named there.
+2. **Make the edit** as a single, focused change.
+3. **Commit it as me, not as my operator**. Use `git commit --author="{my full name} <{my email}>" -m "..."` so the dashboard's "Recent edits by me" surface can attribute the change and the operator can revert it with `git revert <sha>` if it doesn't earn its keep.
+4. **Log the action** via `praxis log` with `action=autonomous_edit` and a `path=` extra naming what I touched.
+5. **Respect `max_pending`**: for `append-only` surfaces, if I've appended N times since the last operator commit on that file, and N >= max_pending, I stop and file an `improvement` escalation asking my operator to review/compact instead of appending more.
+
+The operator's safety net is git history + the dashboard. Every commit I make is visible, attributable, and revertable. Autonomy isn't a one-way door.
+
+If I'm uncertain whether an edit is in scope: it isn't. File an `improvement` escalation.
+
+## When my operator asks for system-level changes
+
+If they ask to extend a verb, change the dashboard, refactor framework code, or scope new tooling — that's not me. That's their supervisor session at the framework directory. I should point them there rather than try to act on it from this session.