pi-soly 0.8.0 → 0.9.0

package/agents-install.ts

@@ -34,12 +34,14 @@ const SHIPPED_SKILLS = [
 ] as const;
 
 /** Where pi looks for user agents. Respects HOME/USERPROFILE for
- *  testability (otherwise we'd always write to the real user home). */
+ *  testability (otherwise we'd always write to the real user home).
+ *  Path scheme: `<root>/.agents/agents/` (vendor-neutral) and
+ *  `<root>/.pi/agent/agents/` (pi native, legacy). */
 function userAgentsDirs(): string[] {
 	const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
 	return [
-		path.join(home, ".agents"),                          // vendor-neutral (preferred)
-		path.join(home, ".pi", "agent", "agents"),           // pi's native
+		path.join(home, ".agents", "agents"),                // vendor-neutral (preferred)
+		path.join(home, ".pi", "agent", "agents"),           // pi native
 	];
 }
 

package/index.ts

@@ -353,10 +353,14 @@ export default function solyExtension(pi: ExtensionAPI) {
 		// Rules sources (priority order, higher wins on relPath collision).
 		// Project rules always beat global rules. .soly/rules.local/ is
 		// gitignored — for personal overrides on top of the project's rules.
+		// .agents/rules/ is the vendor-neutral project-level convention
+		// (same role as the old .claude/rules/).
 		ruleSources = [
 			{ dir: path.join(ctx.cwd, ".soly", "rules.local"), source: "project-soly", sourceLabel: "local", priority: 5 },
 			{ dir: path.join(ctx.cwd, ".soly", "rules"), source: "project-soly", sourceLabel: "soly", priority: 4 },
+			{ dir: path.join(ctx.cwd, ".agents", "rules"), source: "project-agents", sourceLabel: "agents", priority: 3 },
 			{ dir: path.join(os.homedir(), ".soly", "rules"), source: "global-soly", sourceLabel: "soly", priority: 2 },
+			{ dir: path.join(os.homedir(), ".agents", "rules"), source: "global-agents", sourceLabel: "agents", priority: 1 },
 		];
 		refreshRules();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-soly",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Project management framework for pi-coding-agent. Workflows, planning, multi-question picker, agent switcher, live task list — one npm install, zero config.",
   "type": "module",
   "main": "index.ts",

package/skills/soly-framework/SKILL.md

@@ -45,16 +45,13 @@ The **soly** extension adds project-management workflow to [pi-coding-agent](htt
 <project-root>/
 ├── AGENTS.md                      # vendor-neutral agent context (loaded by pi)
 ├── agents.md                      # same as AGENTS.md, lowercase accepted
-├── .agents/                       # project-level agent definitions
-│   ├── project-reviewer.md
-│   └── data-scientist.md
-├── .soly/
+├── .soly/                         # soly state (phases, plans, summaries)
 │   ├── ROADMAP.md                 # phase table
 │   ├── STATE.md                   # current position + decisions log
 │   ├── docs/                      # 0-point intent docs (human-written, locked)
 │   │   ├── vision.md
 │   │   └── architecture.md
-│   ├── rules/                     # project rules (version-controlled)
+│   ├── rules/                     # soly project rules (version-controlled)
 │   │   ├── code-style.md
 │   │   └── testing.md
 │   ├── phases/
@@ -70,8 +67,26 @@ The **soly** extension adds project-management workflow to [pi-coding-agent](htt
 │   ├── iterations/                # per-execution context bundles (auto)
 │   ├── HANDOFF.json               # pause snapshot
 │   └── .continue-here.md          # pause resume marker
+├── .agents/                       # vendor-neutral agent config (per project)
+│   ├── rules/                     # agent rules (loaded with priority 3, after .soly/rules/)
+│   │   ├── code-style.md
+│   │   └── testing.md
+│   ├── skills/                    # project-scoped skills (pi auto-discovers)
+│   │   └── my-skill/
+│   │       └── SKILL.md
+│   ├── docs/                      # agent-specific docs (intent-style)
+│   │   └── architecture.md
+│   └── agents/                    # project-specific agent definitions
+│       ├── project-reviewer.md
+│       └── data-scientist.md
 ```
 
+**Two parallel conventions:** `.soly/` is soly-specific state (phases, plans). `.agents/` is vendor-neutral agent config (works with any AI tool that follows the AGENTS.md standard). The two coexist:
+
+- Use `.soly/` for soly workflow artifacts (PLAN.md, SUMMARY.md, etc.)
+- Use `.agents/` for things other AI tools should also see (rules, skills, agents)
+- Use `AGENTS.md` for top-level project-wide agent conventions
+
 ## Frontmatter conventions
 
 ### PLAN.md frontmatter (required)
@@ -285,7 +300,7 @@ Intent docs are 0-point — written BEFORE any plan, by humans. They define the
 
 ### Add project-specific agents
 
-Drop a markdown file in `.agents/<name>.md` (project) or `~/.agents/<name>.md` (user):
+Drop a markdown file in `.agents/agents/<name>.md` (project) or `~/.agents/agents/<name>.md` (user):
 
 ```markdown
 ---
@@ -298,7 +313,13 @@ tools: read, bash
 You are a data scientist. ...
 ```
 
-Both `~/.agents/` and `~/.pi/agent/agents/` are read (vendor-neutral preferred). `Ctrl+Tab` to see them in the cycle.
+**Discovered from 4 locations** (priority order):
+1. `<project>/.agents/agents/` — project vendor-neutral (preferred)
+2. `<project>/.pi/agent/agents/` — project pi native (legacy)
+3. `~/.agents/agents/` — user vendor-neutral (preferred)
+4. `~/.pi/agent/agents/` — user pi native (legacy)
+
+`Ctrl+Tab` to see them in the cycle.
 
 ### Add a feature to an existing phase
 
@@ -334,9 +355,9 @@ If `/execute` complains about illegal partial state:
 - ❌ Edit `.soly/rules/` files you didn't write — those are project invariants
 - ❌ Skip the SUMMARY — illegal partial state
 - ❌ Spawn `soly-worker` or `soly-debugger` — use `soly-manager` (mode-switches)
-- ❌ Write rules in code comments — use `.soly/rules/*.md` files
+- ❌ Write rules in code comments — use `.soly/rules/*.md` or `.agents/rules/*.md` files
 - ❌ Edit `.soly/phases/*/PLAN.md` after `status: in_progress` — create a new plan
-- ❌ Put intent docs anywhere other than `.soly/docs/`
+- ❌ Put intent docs anywhere other than `.soly/docs/` (or `.agents/docs/` for vendor-neutral)
 
 ## When in doubt
 

package/switch/core.ts

@@ -65,23 +65,29 @@ export function isValidAgentName(name: string): boolean {
 }
 
 /** Discover agent `.md` files in user dir. */
-/** User agent home directories, in priority order. First existing one
- *  wins for new agent creation; all are read and merged in the cycle.
- *  Honors $HOME / $USERPROFILE so tests can redirect to a tmp dir. */
-export function userAgentDirs(): string[] {
+/** All known agent home directories, in priority order (project wins
+ *  over user-home; user-home `.agents/` wins over pi-native).
+ *  Project-level `.agents/agents/` is a vendor-neutral per-project
+ *  convention — same role as `.soly/` or the old `.claude/`.
+ *  Honors $HOME / $USERPROFILE for testability. */
+export function agentHomeDirs(cwd?: string): string[] {
 	const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
-	return [
-		path.join(home, ".agents"),                          // vendor-neutral (preferred)
-		path.join(home, ".pi", "agent", "agents"),           // pi's native
-	];
+	const dirs: string[] = [];
+	if (cwd) {
+		dirs.push(path.join(cwd, ".agents", "agents"));         // project (vendor-neutral, preferred)
+		dirs.push(path.join(cwd, ".pi", "agent", "agents"));    // project (pi native, legacy)
+	}
+	dirs.push(path.join(home, ".agents", "agents"));              // user (vendor-neutral)
+	dirs.push(path.join(home, ".pi", "agent", "agents"));         // user (pi native, legacy)
+	return dirs;
 }
 
-/** Read all user agent names from every registered home dir. Dedupes,
- *  first-occurrence wins. */
-export function discoverUserAgents(): string[] {
+/** Read all agent names from every home dir. Dedupes, first-occurrence
+ *  wins. If cwd is provided, project dirs are scanned first. */
+export function discoverUserAgents(cwd?: string): string[] {
 	const seen = new Set<string>();
 	const out: string[] = [];
-	for (const dir of userAgentDirs()) {
+	for (const dir of agentHomeDirs(cwd)) {
 		if (!fs.existsSync(dir)) continue;
 		let entries: string[];
 		try {
@@ -111,9 +117,9 @@ export function discoverUserAgents(): string[] {
 }
 
 /** Build the full cycle of available agents. Built-ins first, then
- *  user-discovered (from all user agent home dirs). Dedupes while
- *  preserving first-occurrence order. */
-export function availableAgents(): string[] {
+ *  project-level agents (if cwd given), then user-home agents.
+ *  Dedupes while preserving first-occurrence order. */
+export function availableAgents(cwd?: string): string[] {
 	const out: string[] = [];
 	const seen = new Set<string>();
 	const push = (n: string) => {
@@ -123,7 +129,7 @@ export function availableAgents(): string[] {
 		}
 	};
 	for (const a of BUILTIN_AGENTS) push(a);
-	for (const a of discoverUserAgents()) push(a);
+	for (const a of discoverUserAgents(cwd)) push(a);
 	return out;
 }
 
@@ -165,8 +171,8 @@ export function formatAgentSwitchNotify(prev: string, next: string): string {
 }
 
 /** Group agents: built-ins + user-defined. */
-export function groupedAvailableAgents(): Array<{ header: string; agents: string[] }> {
-	const all = availableAgents();
+export function groupedAvailableAgents(cwd?: string): Array<{ header: string; agents: string[] }> {
+	const all = availableAgents(cwd);
 	const groups: Array<{ header: string; agents: string[] }> = [];
 	const builtin = all.filter((a) => BUILTIN_AGENTS.includes(a));
 	if (builtin.length > 0) groups.push({ header: "built-in", agents: builtin });

package/switch/index.ts

@@ -45,7 +45,7 @@ export default function piSwitchExtension(pi: ExtensionAPI) {
 	let lastUi: ExtensionUIContext | null = null;
 
 	function refreshCycle(): void {
-		cycle = availableAgents();
+		cycle = availableAgents(cwd);
 		if (!cycle.includes(currentAgent)) currentAgent = DEFAULT_AGENT;
 	}
 
@@ -177,8 +177,8 @@ function openPicker(ui: ExtensionUIContext): void {
 function handleSet(name: string, ui: ExtensionUIContext): void {
 	const target = parseAgentName(name);
 	if (!target) return ui.notify(`pi-switch: invalid name "${name}".`, "error");
-	if (!availableAgents().includes(target)) {
-		return ui.notify(`pi-switch: unknown "${target}". available: ${availableAgents().join(", ")}`, "error");
+	if (!availableAgents(cwd).includes(target)) {
+		return ui.notify(`pi-switch: unknown "${target}". available: ${availableAgents(cwd).join(", ")}`, "error");
 	}
 	setAgentRef(target);
 }
@@ -314,7 +314,7 @@ you have a specific reason to change it.
 }
 
 function doctorReport(): string {
-	const cycle = availableAgents();
+	const cycle = availableAgents(cwd);
 	const userDir = path.join(os.homedir(), ".pi", "agent", "agents");
 	const lines: string[] = ["pi-switch doctor:", ""];
 	const builtins = cycle.filter((a) => BUILTIN_AGENTS.includes(a));

package/switch/tests/core.test.ts

@@ -123,14 +123,14 @@ describe("groupedAvailableAgents", () => {
 		expect(groups[0]?.header).toBe("built-in");
 	});
 	test("includes user group when present", () => {
-		// Use HOME override so the new ~.agents/ scan picks up our fixture
+		// Use HOME override so the new ~.agents/agents/ scan picks up our fixture
 		const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
 		const prevHome = process.env.HOME;
 		const prevUserProfile = process.env.USERPROFILE;
 		const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "pis-home-"));
 		process.env.HOME = tmp;
 		process.env.USERPROFILE = tmp;
-		const agentsDir = path.join(tmp, ".agents");
+		const agentsDir = path.join(tmp, ".agents", "agents");
 		fs.mkdirSync(agentsDir, { recursive: true });
 		fs.writeFileSync(path.join(agentsDir, "my.md"), "---\nname: my-helper\n---\n# body\n");
 		const groups = groupedAvailableAgents();
@@ -141,6 +141,17 @@ describe("groupedAvailableAgents", () => {
 		process.env.USERPROFILE = prevUserProfile ?? home;
 		fs.rmSync(tmp, { recursive: true, force: true });
 	});
+
+	test("includes project agent when present (cwd scope)", () => {
+		const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), "pis-proj-"));
+		const agentsDir = path.join(projectDir, ".agents", "agents");
+		fs.mkdirSync(agentsDir, { recursive: true });
+		fs.writeFileSync(path.join(agentsDir, "proj.md"), "---\nname: project-helper\n---\n# body\n");
+		const groups = groupedAvailableAgents(projectDir);
+		const userGroup = groups.find((g) => g.header === "user-defined");
+		expect(userGroup?.agents).toContain("project-helper");
+		fs.rmSync(projectDir, { recursive: true, force: true });
+	});
 });
 
 // ---------------------------------------------------------------------------