create-plico 0.1.1 → 0.1.2

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/README.md CHANGED
@@ -11,3 +11,5 @@ Scaffold generator for the internal-ops starter project. Part of [Plico](https:/
11
11
  `create-plico my-plico --provider anthropic|openai|google|openai-compatible` configures a model and writes the matching `.env.example` and adapter dependency. The interactive flow asks for the provider; without `--provider`, a non-interactive run configures none. The scaffold also writes a `package.json` with `dev`, `validate` and `eval` scripts, `@plico-ai/cli` as a dev dependency, and a `.gitignore` for `.plico/` and `.env`.
12
12
 
13
13
  The generated scaffold includes the required Plico project files and directories so it is immediately valid and can complete `plico run --dry` and pass `plico eval` (it ships `evals/smoke.script.json`) after `npm install`.
14
+
15
+ Docs: [plico.sohab.dev](https://plico.sohab.dev). For AI coding agents: [llms.txt](https://plico.sohab.dev/llms.txt).
package/dist/cli.js CHANGED
@@ -71,6 +71,7 @@ export async function main(argv, prompts = defaultScaffoldPrompts) {
71
71
  ...(provider ? { provider } : {}),
72
72
  });
73
73
  console.log(`Created Plico scaffold in ${targetDir}`);
74
+ console.log("Next: cd in, npm install, npm run validate. Docs: https://plico.sohab.dev (for AI agents: /llms.txt)");
74
75
  return 0;
75
76
  }
76
77
  catch (error) {
package/dist/files.d.ts CHANGED
@@ -4,6 +4,8 @@ export declare function packageFile(version: string, provider?: ScaffoldProvider
4
4
  export declare function envExampleFile(provider?: ScaffoldProvider): string;
5
5
  export declare function gitignoreFile(): string;
6
6
  export declare function agentFile(projectName: string): string;
7
+ export declare function projectAgentsFile(projectName: string): string;
8
+ export declare function projectClaudeFile(): string;
7
9
  export declare function triageSkillFile(): string;
8
10
  export declare function toolsReadmeFile(): string;
9
11
  export declare function smokeEvalFile(): string;
package/dist/files.js CHANGED
@@ -81,6 +81,82 @@ export function agentFile(projectName) {
81
81
  "",
82
82
  ].join("\n");
83
83
  }
84
+ export function projectAgentsFile(projectName) {
85
+ return `# ${projectName}: instructions for coding agents
86
+
87
+ This is a [Plico](https://plico.sohab.dev) project: the agent is the files in this folder. Plico docs as plain Markdown: https://plico.sohab.dev/llms.txt (everything in one file: https://plico.sohab.dev/llms-full.txt).
88
+
89
+ ## Layout
90
+
91
+ - \`agent.md\` is the agent's instructions. Edit it to change behaviour.
92
+ - \`plico.config.ts\` is the project config (\`defineConfig\` from \`@plico-ai/sdk\`): name, optional \`model\`, optional \`approvals\`.
93
+ - \`skills/<name>/SKILL.md\` holds a skill. It needs a \`description\` in its frontmatter.
94
+ - \`tools/<name>.tool.ts\` holds one tool as a default export (below).
95
+ - \`evals/<name>.script.json\` holds one eval case (below).
96
+ - \`artifacts/\` and \`memory/\` are required folders. Leave them in place.
97
+
98
+ ## Add a tool
99
+
100
+ \`\`\`ts
101
+ import { defineTool } from "@plico-ai/sdk";
102
+
103
+ export default defineTool({
104
+ name: "issue_refund", // unique, snake_case
105
+ description: "Refund an order.",
106
+ inputSchema: {
107
+ type: "object",
108
+ properties: { orderId: { type: "string" } },
109
+ required: ["orderId"],
110
+ additionalProperties: false,
111
+ },
112
+ capabilities: ["payments:write"], // required, recorded only
113
+ approval: { required: true, reason: "Moves money." }, // required; true makes the run wait for a person
114
+ handler: async ({ orderId }, ctx) => ({ orderId, status: "refunded" }),
115
+ });
116
+ \`\`\`
117
+
118
+ \`capabilities\` and \`approval\` are required. For a Zod \`inputSchema\`, add \`zod\` to this project first.
119
+
120
+ ## Add an eval
121
+
122
+ A case is a script plus an optional \`expect\`. It uses no model and no API key:
123
+
124
+ \`\`\`json
125
+ {
126
+ "description": "A refund waits for approval, then is approved.",
127
+ "script": [
128
+ { "type": "tool.call", "toolName": "issue_refund", "arguments": { "orderId": "A-1" },
129
+ "result": { "status": "refunded" } },
130
+ { "type": "approval.decide", "approved": true },
131
+ { "type": "assistant.output", "content": "Refunded." }
132
+ ],
133
+ "expect": { "status": "completed", "outputContains": "Refunded" }
134
+ }
135
+ \`\`\`
136
+
137
+ Steps are \`assistant.output\` (\`content\`), \`tool.call\` (\`toolName\`, \`arguments\`, \`result\` is required because evals do not run handlers, or \`"live": true\` to run the handler), \`approval.decide\` (\`approved\`, right after a tool call that needs approval) and \`artifact.write\` (\`files\`). Leave out \`approval.decide\` and the run stops as \`waiting\`, so \`"expect": { "status": "waiting" }\` tests that a tool is held. \`approved: false\` ends the run as \`failed\`.
138
+
139
+ ## Check your work
140
+
141
+ \`\`\`bash
142
+ npm run validate # plico validate: layout, config, tool and skill names
143
+ npm run eval # plico eval: every case in evals/; exit 1 on any failure or no cases
144
+ npx plico run --dry . # runs with a scripted model; add --script <file> for your own steps
145
+ \`\`\`
146
+
147
+ \`plico run --dry\` exits 0 on completion, 2 when a run is waiting for approval and 1 on failure. Run \`npx plico <command> --help\` for a command's flags.
148
+
149
+ ## Rules
150
+
151
+ - Keep secrets in \`.env\`, never in \`agent.md\`, tools or config. Events record tool arguments and results.
152
+ - Do not edit \`.plico/\`: it holds saved runs.
153
+ - Do not ask for a model key to test. Use \`--dry\` and evals.
154
+ - With a model, \`plico serve --studio .\` opens Studio, a local UI to chat, read run events and approve tool calls.
155
+ `;
156
+ }
157
+ export function projectClaudeFile() {
158
+ return "@AGENTS.md\n";
159
+ }
84
160
  export function triageSkillFile() {
85
161
  return [
86
162
  "---",
@@ -100,13 +176,14 @@ export function toolsReadmeFile() {
100
176
  "",
101
177
  "Add TypeScript tool modules here when the project needs executable helpers.",
102
178
  "",
103
- "Keep the public contract file-first until tools are explicitly required.",
179
+ "Each tool is one `<name>.tool.ts` file with a default export from `defineTool`.",
104
180
  "",
105
- "A tool handler receives `(input, { signal, idempotencyKey })`. A run that is interrupted can repeat",
106
- "the tool call that was in flight, so pass `idempotencyKey` to any API that takes one. The key is",
107
- "stable for a call, and `signal` aborts when the run is cancelled.",
181
+ "A tool handler receives `(input, ctx)`. `ctx` has `signal`, `idempotencyKey`, `artifacts` and",
182
+ "`context`. A run that is interrupted can repeat the tool call that was in flight, so pass",
183
+ "`idempotencyKey` to any API that takes one. The key is stable for a call, and `signal` aborts",
184
+ "when the run is cancelled.",
108
185
  "",
109
- "Set `inputSchema` to a JSON Schema object or a Zod 3 or 4 schema. Plico validates each call and",
186
+ "Set `inputSchema` to a JSON Schema object or a Zod 4 schema. Plico validates each call and",
110
187
  "sends JSON Schema to the model. Parsed Zod values, including defaults, reach the handler. Add",
111
188
  "`zod` to this project's dependencies before importing it in a tool.",
112
189
  "",
package/dist/providers.js CHANGED
@@ -14,7 +14,7 @@ export const PROVIDER_SETUP = {
14
14
  },
15
15
  google: {
16
16
  label: "Google",
17
- model: "gemini-2.5-flash",
17
+ model: "gemini-3.5-flash",
18
18
  apiKeyEnv: "GOOGLE_GENERATIVE_AI_API_KEY",
19
19
  adapter: "@ai-sdk/google",
20
20
  },
package/dist/scaffold.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import { mkdir, readdir, writeFile } from "node:fs/promises";
2
2
  import { join } from "node:path";
3
3
  import { getProjectPaths, REQUIRED_PROJECT_DIRECTORIES } from "@plico-ai/core";
4
- import { agentFile, artifactsReadmeFile, configFile, envExampleFile, gitignoreFile, memoryReadmeFile, packageFile, projectReadmeFile, smokeEvalFile, toolsReadmeFile, triageSkillFile, } from "./files.js";
4
+ import { agentFile, artifactsReadmeFile, configFile, envExampleFile, gitignoreFile, memoryReadmeFile, packageFile, projectAgentsFile, projectClaudeFile, projectReadmeFile, smokeEvalFile, toolsReadmeFile, triageSkillFile, } from "./files.js";
5
5
  import { readVersion } from "./usage.js";
6
6
  export async function createInternalOpsScaffold(options) {
7
7
  const root = options.targetDir;
@@ -22,6 +22,8 @@ export async function createInternalOpsScaffold(options) {
22
22
  await writeFile(join(projectPaths.directories.memory, "README.md"), memoryReadmeFile(), "utf8");
23
23
  await writeFile(join(projectPaths.directories.artifacts, "README.md"), artifactsReadmeFile(), "utf8");
24
24
  await writeFile(join(root, "README.md"), projectReadmeFile(projectName), "utf8");
25
+ await writeFile(join(root, "AGENTS.md"), projectAgentsFile(projectName), "utf8");
26
+ await writeFile(join(root, "CLAUDE.md"), projectClaudeFile(), "utf8");
25
27
  }
26
28
  async function ensureEmptyTarget(root) {
27
29
  let entries;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-plico",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "Scaffold a Plico agent project",
5
5
  "license": "Apache-2.0",
6
6
  "homepage": "https://plico.sohab.dev",
@@ -40,10 +40,10 @@
40
40
  ],
41
41
  "dependencies": {
42
42
  "@clack/prompts": "^1.6.0",
43
- "@plico-ai/core": "0.1.1"
43
+ "@plico-ai/core": "0.1.2"
44
44
  },
45
45
  "devDependencies": {
46
- "@plico-ai/runtime": "0.1.1"
46
+ "@plico-ai/runtime": "0.1.2"
47
47
  },
48
48
  "engines": {
49
49
  "node": ">=22.18.0"