lalph 0.3.12 → 0.3.14

package/README.md

@@ -8,11 +8,12 @@ A LLM agent orchestrator driven by your chosen source of issues.
 
 ## Features
 
-- Integrate with various issue sources (GitHub Issues, Linear, etc.)
-- Plan mode to generate issues from high-level goals
-- Uses git worktrees to allow for multiple concurrent iterations
-- Creates pull requests for each task, with optional auto-merge for vibe coding
-- Support issue dependencies to ensure correct task order
+- Pull work from an issue source (GitHub Issues, Linear, etc.) and keep task state in sync
+- Projects to group execution settings (enabled state, concurrency, target branch, git flow, review agent)
+- Agent presets to control which CLI agent runs tasks, with optional label-based routing
+- Plan mode to turn a high-level plan into a spec and generate PRD tasks
+- Git worktrees to support multiple concurrent iterations
+- Optional PR flow with auto-merge and support for issue dependencies
 
 ## Installation
 
@@ -28,15 +29,78 @@ npx -y lalph@latest
 
 ## CLI usage
 
-- Run the main loop: `lalph`
-- Run multiple iterations with concurrency: `lalph --iterations 4 --concurrency 2`
+- Run the main loop across enabled projects: `lalph`
+- Run a bounded set of iterations per enabled project: `lalph --iterations 1`
+- Configure projects and per-project concurrency: `lalph projects add`
+- Inspect and configure agent presets: `lalph agents ls`
 - Start plan mode: `lalph plan`
-- Start plan mode without permission prompts: `lalph plan --dangerous`
-- Choose your issue source: `lalph source`
+- Create an issue from your editor: `lalph issue`
+- Choose your issue source integration (applies to all projects): `lalph source`
 
 It is recommended to add `.lalph/` to your `.gitignore` to avoid committing your
 credentials.
 
+## Agent presets
+
+Agent presets define which CLI agent runs tasks (and with what arguments). Lalph
+always needs a default preset and will prompt you to create one on first run if
+it's missing.
+
+Some issue sources support routing: you can associate a preset with a label, and
+issues with that label will run with that preset; anything else uses the default.
+
+```bash
+lalph agents ls
+lalph agents add
+```
+
+## Projects
+
+Projects bundle execution settings for the current repo: whether it is enabled
+for runs, how many tasks can run concurrently, which branch to target, what git
+flow to use, and whether review is enabled.
+
+`lalph` runs across all enabled projects in parallel; for single-project
+commands, you'll be prompted to choose an active project when needed.
+
+```bash
+lalph projects add
+lalph projects toggle
+```
+
+## Plan mode
+
+Plan mode opens an editor so you can write a high-level plan. On save, lalph
+generates a specification under `--specs` and then creates PRD tasks from it.
+
+Use `--dangerous` to skip permission prompts during spec generation, and `--new`
+to create a project before starting plan mode.
+
+```bash
+lalph plan
+lalph plan tasks .specs/my-spec.md
+```
+
+## Creating issues
+
+`lalph issue` opens a new-issue template in your editor. When you save and close
+the file, the issue is created in the current issue source.
+
+Anything below the front matter is used as the issue description.
+
+Front matter fields:
+
+- `title`: short issue title
+- `priority`: number (0 = none, 1 = urgent, 2 = high, 3 = normal, 4 = low)
+- `estimate`: number of points, or `null`
+- `blockedBy`: array of issue identifiers
+- `autoMerge`: whether to mark this issue for auto-merge when applicable
+
+```bash
+lalph issue
+lalph i
+```
+
 ## Development
 
 - Install dependencies: `pnpm install`

package/dist/cli.mjs

@@ -144155,16 +144155,49 @@ var LinearError = class extends ErrorClass("lalph/LinearError")({
 	cause: Defect
 }) {};
 const selectedProjectId = new ProjectSetting("linear.selectedProjectId", String$1);
-const selectProject$1 = gen(function* () {
+const createLinearProject = gen(function* () {
 	const linear = yield* Linear;
 	const projects = yield* runCollect(linear.projects);
-	const project = yield* autoComplete({
-		message: "Select a Linear project",
-		choices: projects.map((project) => ({
-			title: project.name,
-			value: project
+	const projectName = yield* text$2({
+		message: "Project name",
+		validate(input) {
+			const name = input.trim();
+			if (name.length === 0) return fail$4("Project name cannot be empty");
+			if (projects.some((project) => project.name.toLowerCase() === name.toLowerCase())) return fail$4("A project with this name already exists");
+			return succeed$1(name);
+		}
+	});
+	const teams = yield* linear.use((client) => client.teams()).pipe(map$8((teamConnection) => teamConnection.nodes));
+	const teamId = yield* autoComplete({
+		message: "Select a team for the new project",
+		choices: teams.map((team) => ({
+			title: team.name,
+			value: team.id
 		}))
 	});
+	const created = yield* linear.use((client) => client.createProject({
+		name: projectName,
+		teamIds: [teamId]
+	}));
+	return yield* linear.use(() => created.project);
+});
+const selectProject$1 = gen(function* () {
+	const linear = yield* Linear;
+	const choices = [{
+		title: "Create new",
+		value: { _tag: "create" }
+	}, ...(yield* runCollect(linear.projects)).map((project) => ({
+		title: project.name,
+		value: {
+			_tag: "existing",
+			project
+		}
+	}))];
+	const selected = yield* autoComplete({
+		message: "Select a Linear project",
+		choices
+	});
+	const project = selected._tag === "existing" ? selected.project : yield* createLinearProject;
 	yield* Settings.setProject(selectedProjectId, some$2(project.id));
 	return project;
 });
@@ -152025,18 +152058,18 @@ const runProject = fnUntraced(function* (options) {
 	}
 	yield* awaitEmpty(fibers);
 }, (effect, options) => annotateLogs(effect, { project: options.project.id }));
-const iterations = integer("iterations").pipe(withDescription$1("Number of iterations to run, defaults to unlimited"), withAlias("i"), withDefault(Number.POSITIVE_INFINITY));
-const maxIterationMinutes = integer("max-minutes").pipe(withDescription$1("Maximum number of minutes to allow an iteration to run. Defaults to 90 minutes. Env variable: LALPH_MAX_MINUTES"), withFallbackConfig(int("LALPH_MAX_MINUTES")), withDefault(90));
-const stallMinutes = integer("stall-minutes").pipe(withDescription$1("If no activity occurs for this many minutes, the iteration will be stopped. Defaults to 5 minutes. Env variable: LALPH_STALL_MINUTES"), withFallbackConfig(int("LALPH_STALL_MINUTES")), withDefault(5));
-const specsDirectory = directory("specs").pipe(withDescription$1("Directory to store plan specifications. Env variable: LALPH_SPECS"), withAlias("s"), withFallbackConfig(string$1("LALPH_SPECS")), withDefault(".specs"));
-const verbose = boolean("verbose").pipe(withDescription$1("Enable verbose logging"), withAlias("v"));
+const iterations = integer("iterations").pipe(withDescription$1("Limit how many task iterations run per enabled project (default: unlimited). Use -i 1 to run a single iteration and exit."), withAlias("i"), withDefault(Number.POSITIVE_INFINITY));
+const maxIterationMinutes = integer("max-minutes").pipe(withDescription$1("Timeout an iteration if execution (and review, if enabled) exceeds this many minutes (default: LALPH_MAX_MINUTES or 90)."), withFallbackConfig(int("LALPH_MAX_MINUTES")), withDefault(90));
+const stallMinutes = integer("stall-minutes").pipe(withDescription$1("Fail an iteration if the agent stops responding for this many minutes (default: LALPH_STALL_MINUTES or 5)."), withFallbackConfig(int("LALPH_STALL_MINUTES")), withDefault(5));
+const specsDirectory = directory("specs").pipe(withDescription$1("Directory where plan specs are written and read (default: LALPH_SPECS or .specs)."), withAlias("s"), withFallbackConfig(string$1("LALPH_SPECS")), withDefault(".specs"));
+const verbose = boolean("verbose").pipe(withDescription$1("Increase log output for debugging. Use -v when you need detailed logs."), withAlias("v"));
 const commandRoot = make$35("lalph", {
 	iterations,
 	maxIterationMinutes,
 	stallMinutes,
 	specsDirectory,
 	verbose
-}).pipe(withHandler(fnUntraced(function* ({ iterations, maxIterationMinutes, stallMinutes, specsDirectory }) {
+}).pipe(withDescription("Run the task loop across all enabled projects in parallel: pull issues from the current issue source and execute them with your configured agent preset(s). Use --iterations for a bounded run, and configure per-project concurrency via lalph projects edit."), withHandler(fnUntraced(function* ({ iterations, maxIterationMinutes, stallMinutes, specsDirectory }) {
 	yield* getDefaultCliAgentPreset;
 	let allProjects = yield* getAllProjects;
 	if (allProjects.length === 0) {
@@ -152115,8 +152148,8 @@ const agentTasker = fnUntraced(function* (options) {
 const specificationPath = path("spec", {
 	pathType: "file",
 	mustExist: true
-}).pipe(withDescription$2("Path to the specification file to convert into tasks"));
-const commandPlanTasks = make$35("tasks", { specificationPath }).pipe(withDescription("Convert a specification into tasks"), withHandler(fnUntraced(function* ({ specificationPath }) {
+}).pipe(withDescription$2("Required. Path to an existing specification file to convert into tasks"));
+const commandPlanTasks = make$35("tasks", { specificationPath }).pipe(withDescription("Convert an existing specification file into PRD tasks (without re-running plan mode)"), withHandler(fnUntraced(function* ({ specificationPath }) {
 	const { specsDirectory } = yield* commandRoot;
 	const fs = yield* FileSystem;
 	const pathService = yield* Path$1;
@@ -152176,12 +152209,12 @@ var Editor = class extends Service$1()("lalph/Editor", { make: gen(function* ()
 
 //#endregion
 //#region src/commands/plan.ts
-const dangerous = boolean("dangerous").pipe(withAlias("d"), withDescription$1("Enable dangerous mode (skip permission prompts) during plan generation"));
-const withNewProject = boolean("new").pipe(withAlias("n"), withDescription$1("Create a new project before starting plan mode"));
+const dangerous = boolean("dangerous").pipe(withAlias("d"), withDescription$1("Skip permission prompts while generating the specification from your plan"));
+const withNewProject = boolean("new").pipe(withAlias("n"), withDescription$1("Create a new project (via prompts) before starting plan mode"));
 const commandPlan = make$35("plan", {
 	dangerous,
 	withNewProject
-}).pipe(withDescription("Iterate on an issue plan and create PRD tasks"), withHandler(fnUntraced(function* ({ dangerous, withNewProject }) {
+}).pipe(withDescription("Open an editor to draft a plan; on save, generate a specification under --specs and then create PRD tasks from it. Use --new to create a project first; use --dangerous to skip permission prompts during spec generation."), withHandler(fnUntraced(function* ({ dangerous, withNewProject }) {
 	const thePlan = yield* (yield* Editor).editTemp({ suffix: ".md" });
 	if (isNone(thePlan)) return;
 	yield* gen(function* () {
@@ -152207,6 +152240,10 @@ const plan = fnUntraced(function* (options) {
 		preset
 	});
 	const planDetails = yield* pipe(fs.readFileString(pathService.join(worktree.directory, ".lalph", "plan.json")), flatMap$2(decodeEffect(PlanDetails)), mapError$2(() => new SpecNotFound()));
+	if (isSome(options.targetBranch)) yield* commitAndPushSpecification({
+		specsDirectory: options.specsDirectory,
+		targetBranch: options.targetBranch.value
+	});
 	yield* log$1("Converting specification into tasks");
 	yield* agentTasker({
 		specificationPath: planDetails.specification,
@@ -152224,6 +152261,28 @@ const plan = fnUntraced(function* (options) {
 var SpecNotFound = class extends TaggedError("SpecNotFound") {
 	message = "The AI agent failed to produce a specification.";
 };
+var SpecGitError = class extends TaggedError("SpecGitError") {};
+const commitAndPushSpecification = fnUntraced(function* (options) {
+	const worktree = yield* Worktree;
+	const absSpecsDirectory = (yield* Path$1).join(worktree.directory, options.specsDirectory);
+	const git = (args) => make$23("git", [...args], {
+		cwd: worktree.directory,
+		stdout: "inherit",
+		stderr: "inherit"
+	}).pipe(exitCode);
+	if ((yield* git(["add", absSpecsDirectory])) !== 0) return yield* new SpecGitError({ message: "Failed to stage specification changes." });
+	if ((yield* git([
+		"commit",
+		"-m",
+		"Update plan specification"
+	])) !== 0) return yield* new SpecGitError({ message: "Failed to commit the generated specification changes." });
+	const parsed = parseBranch(options.targetBranch);
+	yield* git([
+		"push",
+		parsed.remote,
+		`HEAD:${parsed.branch}`
+	]);
+}, ignore({ log: "Warn" }));
 const PlanDetails = fromJsonString(Struct({ specification: String$1 }));
 
 //#endregion
@@ -152279,8 +152338,8 @@ const handler$1 = flow(withHandler(fnUntraced(function* () {
 		console.log(`URL: ${created.url}`);
 	}).pipe(provide$1([layerProjectIdPrompt, CurrentIssueSource.layer]));
 })), provide(Editor.layer));
-const commandIssue = make$35("issue").pipe(withDescription("Create a new issue in the selected issue source"), handler$1);
-const commandIssueAlias = make$35("i").pipe(withDescription("Alias for 'issue' command"), handler$1);
+const commandIssue = make$35("issue").pipe(withDescription("Create a new issue in your editor."), handler$1);
+const commandIssueAlias = make$35("i").pipe(withDescription("Alias for 'issue' (create a new issue in your editor)."), handler$1);
 
 //#endregion
 //#region src/commands/edit.ts
@@ -152288,20 +152347,20 @@ const handler = withHandler(fnUntraced(function* () {
 	const prd = yield* Prd;
 	yield* (yield* Editor).edit(prd.path);
 }, provide$1([Prd.layerLocalProvided.pipe(provideMerge(layerProjectIdPrompt)), Editor.layer])));
-const commandEdit = make$35("edit").pipe(withDescription("Open the prd.yml file in your editor"), handler);
-const commandEditAlias = make$35("e").pipe(withDescription("Alias for 'edit' command"), handler);
+const commandEdit = make$35("edit").pipe(withDescription("Open the selected project's .lalph/prd.yml in your editor."), handler);
+const commandEditAlias = make$35("e").pipe(withDescription("Alias for 'edit' (open the selected project's .lalph/prd.yml in your editor)."), handler);
 
 //#endregion
 //#region src/commands/source.ts
-const commandSource = make$35("source").pipe(withDescription("Select the issue source to use"), withHandler(() => selectIssueSource), provide(Settings.layer));
+const commandSource = make$35("source").pipe(withDescription("Select the issue source to use (e.g. GitHub Issues or Linear). This applies to all projects."), withHandler(() => selectIssueSource), provide(Settings.layer));
 
 //#endregion
 //#region package.json
-var version = "0.3.12";
+var version = "0.3.14";
 
 //#endregion
 //#region src/commands/projects/ls.ts
-const commandProjectsLs = make$35("ls").pipe(withDescription("List all configured projects and their settings"), withHandler(fnUntraced(function* () {
+const commandProjectsLs = make$35("ls").pipe(withDescription("List configured projects and how they run (enabled state, concurrency, branch, git flow, review agent)."), withHandler(fnUntraced(function* () {
 	const meta = yield* CurrentIssueSource;
 	const source = yield* IssueSource;
 	console.log("Issue source:", meta.name);
@@ -152325,11 +152384,11 @@ const commandProjectsLs = make$35("ls").pipe(withDescription("List all configure
 
 //#endregion
 //#region src/commands/projects/add.ts
-const commandProjectsAdd = make$35("add").pipe(withDescription("Add a new project"), withHandler(() => addOrUpdateProject()), provide(Settings.layer), provide(CurrentIssueSource.layer));
+const commandProjectsAdd = make$35("add").pipe(withDescription("Add a project and configure its execution settings (concurrency, target branch, git flow, review agent) and issue source settings."), withHandler(() => addOrUpdateProject()), provide(Settings.layer), provide(CurrentIssueSource.layer));
 
 //#endregion
 //#region src/commands/projects/rm.ts
-const commandProjectsRm = make$35("rm").pipe(withDescription("Remove a project"), withHandler(fnUntraced(function* () {
+const commandProjectsRm = make$35("rm").pipe(withDescription("Remove a project from the configured list and delete its stored state under .lalph/projects."), withHandler(fnUntraced(function* () {
 	const fs = yield* FileSystem;
 	const pathService = yield* Path$1;
 	const projects = yield* getAllProjects;
@@ -152343,14 +152402,14 @@ const commandProjectsRm = make$35("rm").pipe(withDescription("Remove a project")
 
 //#endregion
 //#region src/commands/projects/edit.ts
-const commandProjectsEdit = make$35("edit").pipe(withDescription("Modify a project"), withHandler(fnUntraced(function* () {
+const commandProjectsEdit = make$35("edit").pipe(withDescription("Edit a project's execution settings (concurrency, target branch, git flow, review agent) and issue source settings."), withHandler(fnUntraced(function* () {
 	if ((yield* getAllProjects).length === 0) return yield* log$1("No projects available to edit.");
 	yield* addOrUpdateProject(yield* selectProject);
 })), provide(Settings.layer), provide(CurrentIssueSource.layer));
 
 //#endregion
 //#region src/commands/projects/toggle.ts
-const commandProjectsToggle = make$35("toggle").pipe(withDescription("Enable or disable projects"), withHandler(fnUntraced(function* () {
+const commandProjectsToggle = make$35("toggle").pipe(withDescription("Enable or disable configured projects for lalph runs."), withHandler(fnUntraced(function* () {
 	const projects = yield* getAllProjects;
 	if (projects.length === 0) return yield* log$1("No projects available to toggle.");
 	const enabled = yield* multiSelect({
@@ -152376,12 +152435,12 @@ const subcommands$1 = withSubcommands([
 	commandProjectsToggle,
 	commandProjectsRm
 ]);
-const commandProjects = make$35("projects").pipe(withDescription("Manage projects"), subcommands$1);
-const commandProjectsAlias = make$35("p").pipe(withDescription("Alias for 'projects' command"), subcommands$1);
+const commandProjects = make$35("projects").pipe(withDescription("Manage projects and their execution settings (enabled state, concurrency, target branch, git flow, review agent). Use 'ls' to inspect and 'add', 'edit', or 'toggle' to configure."), subcommands$1);
+const commandProjectsAlias = make$35("p").pipe(withDescription("Alias for 'projects'."), subcommands$1);
 
 //#endregion
 //#region src/commands/sh.ts
-const commandSh = make$35("sh").pipe(withDescription("Enter an interactive shell in the worktree"), withHandler(fnUntraced(function* () {
+const commandSh = make$35("sh").pipe(withDescription("Launch an interactive shell in the active project's worktree."), withHandler(fnUntraced(function* () {
 	const worktree = yield* Worktree;
 	const fs = yield* FileSystem;
 	const pathService = yield* Path$1;
@@ -152397,7 +152456,7 @@ const commandSh = make$35("sh").pipe(withDescription("Enter an interactive shell
 
 //#endregion
 //#region src/commands/agents/ls.ts
-const commandAgentsLs = make$35("ls").pipe(withDescription("List all configured CLI agent presets"), withHandler(fnUntraced(function* () {
+const commandAgentsLs = make$35("ls").pipe(withDescription("List configured agent presets (preset ids, agent, arguments, and any issue-source options)."), withHandler(fnUntraced(function* () {
 	const meta = yield* CurrentIssueSource;
 	const source = yield* IssueSource;
 	console.log("Issue source:", meta.name);
@@ -152419,11 +152478,11 @@ const commandAgentsLs = make$35("ls").pipe(withDescription("List all configured
 
 //#endregion
 //#region src/commands/agents/add.ts
-const commandAgentsAdd = make$35("add").pipe(withDescription("Add a new CLI agent preset"), withHandler(() => addOrUpdatePreset()), provide(Settings.layer), provide(CurrentIssueSource.layer));
+const commandAgentsAdd = make$35("add").pipe(withDescription("Add a new agent preset (interactive prompt for CLI agent, arguments, and any issue-source options)."), withHandler(() => addOrUpdatePreset()), provide(Settings.layer), provide(CurrentIssueSource.layer));
 
 //#endregion
 //#region src/commands/agents/rm.ts
-const commandAgentsRm = make$35("rm").pipe(withDescription("Remove a CLI agent preset"), withHandler(fnUntraced(function* () {
+const commandAgentsRm = make$35("rm").pipe(withDescription("Remove an agent preset (select a preset to delete from your configuration)."), withHandler(fnUntraced(function* () {
 	const presets = yield* getAllCliAgentPresets;
 	if (presets.length === 0) return yield* log$1("There are no presets to remove.");
 	const preset = yield* selectCliAgentPreset;
@@ -152433,7 +152492,7 @@ const commandAgentsRm = make$35("rm").pipe(withDescription("Remove a CLI agent p
 
 //#endregion
 //#region src/commands/agents/edit.ts
-const commandAgentsEdit = make$35("edit").pipe(withDescription("Modify a CLI agent preset"), withHandler(fnUntraced(function* () {
+const commandAgentsEdit = make$35("edit").pipe(withDescription("Edit an existing agent preset (interactive prompt to update agent, arguments, and any issue-source options)."), withHandler(fnUntraced(function* () {
 	if ((yield* getAllCliAgentPresets).length === 0) return yield* log$1("No presets available to edit.");
 	yield* addOrUpdatePreset({ existing: yield* selectCliAgentPreset });
 })), provide(Settings.layer), provide(CurrentIssueSource.layer));
@@ -152446,8 +152505,8 @@ const subcommands = withSubcommands([
 	commandAgentsEdit,
 	commandAgentsRm
 ]);
-const commandAgents = make$35("agents").pipe(withDescription("Manage CLI agent presets"), subcommands);
-const commandAgentsAlias = make$35("a").pipe(withDescription("Alias for 'agents' command"), subcommands);
+const commandAgents = make$35("agents").pipe(withDescription("Manage agent presets used to run tasks. Use 'ls' to inspect presets and 'add'/'edit' to configure agents, arguments, and any issue-source options."), subcommands);
+const commandAgentsAlias = make$35("a").pipe(withDescription("Alias for 'agents' (manage agent presets used to run tasks)."), subcommands);
 
 //#endregion
 //#region src/cli.ts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "lalph",
   "type": "module",
-  "version": "0.3.12",
+  "version": "0.3.14",
   "publishConfig": {
     "access": "public"
   },

package/src/Linear.ts

@@ -539,19 +539,81 @@ const selectedProjectId = new ProjectSetting(
   "linear.selectedProjectId",
   Schema.String,
 )
+type ProjectSelection =
+  | {
+      readonly _tag: "create"
+    }
+  | {
+      readonly _tag: "existing"
+      readonly project: LinearProject
+    }
+const createLinearProject = Effect.gen(function* () {
+  const linear = yield* Linear
+  const projects = yield* Stream.runCollect(linear.projects)
+  const projectName = yield* Prompt.text({
+    message: "Project name",
+    validate(input) {
+      const name = input.trim()
+      if (name.length === 0) {
+        return Effect.fail("Project name cannot be empty")
+      }
+      if (
+        projects.some(
+          (project) => project.name.toLowerCase() === name.toLowerCase(),
+        )
+      ) {
+        return Effect.fail("A project with this name already exists")
+      }
+      return Effect.succeed(name)
+    },
+  })
+  const teams = yield* linear
+    .use((client) => client.teams())
+    .pipe(Effect.map((teamConnection) => teamConnection.nodes))
+  const teamId = yield* Prompt.autoComplete({
+    message: "Select a team for the new project",
+    choices: teams.map((team) => ({
+      title: team.name,
+      value: team.id,
+    })),
+  })
+  const created = yield* linear.use((client) =>
+    client.createProject({
+      name: projectName,
+      teamIds: [teamId],
+    }),
+  )
+  return yield* linear.use(() => created.project!)
+})
 const selectProject = Effect.gen(function* () {
   const linear = yield* Linear
 
   const projects = yield* Stream.runCollect(linear.projects)
-
-  const project = yield* Prompt.autoComplete({
-    message: "Select a Linear project",
-    choices: projects.map((project) => ({
+  const choices: ReadonlyArray<{
+    readonly title: string
+    readonly value: ProjectSelection
+  }> = [
+    {
+      title: "Create new",
+      value: { _tag: "create" },
+    },
+    ...projects.map((project) => ({
       title: project.name,
-      value: project,
+      value: {
+        _tag: "existing" as const,
+        project,
+      },
     })),
+  ]
+
+  const selected = yield* Prompt.autoComplete({
+    message: "Select a Linear project",
+    choices,
   })
 
+  const project =
+    selected._tag === "existing" ? selected.project : yield* createLinearProject
+
   yield* Settings.setProject(selectedProjectId, Option.some(project.id))
 
   return project

package/src/commands/agents/add.ts

@@ -4,7 +4,9 @@ import { Settings } from "../../Settings.ts"
 import { addOrUpdatePreset } from "../../Presets.ts"
 
 export const commandAgentsAdd = Command.make("add").pipe(
-  Command.withDescription("Add a new CLI agent preset"),
+  Command.withDescription(
+    "Add a new agent preset (interactive prompt for CLI agent, arguments, and any issue-source options).",
+  ),
   Command.withHandler(() => addOrUpdatePreset()),
   Command.provide(Settings.layer),
   Command.provide(CurrentIssueSource.layer),

package/src/commands/agents/edit.ts

@@ -9,11 +9,13 @@ import {
 } from "../../Presets.ts"
 
 export const commandAgentsEdit = Command.make("edit").pipe(
-  Command.withDescription("Modify a CLI agent preset"),
+  Command.withDescription(
+    "Edit an existing agent preset (interactive prompt to update agent, arguments, and any issue-source options).",
+  ),
   Command.withHandler(
     Effect.fnUntraced(function* () {
-      const projects = yield* getAllCliAgentPresets
-      if (projects.length === 0) {
+      const presets = yield* getAllCliAgentPresets
+      if (presets.length === 0) {
         return yield* Effect.log("No presets available to edit.")
       }
       const preset = yield* selectCliAgentPreset

package/src/commands/agents/ls.ts

@@ -6,7 +6,9 @@ import { Settings } from "../../Settings.ts"
 import { getAllCliAgentPresets } from "../../Presets.ts"
 
 export const commandAgentsLs = Command.make("ls").pipe(
-  Command.withDescription("List all configured CLI agent presets"),
+  Command.withDescription(
+    "List configured agent presets (preset ids, agent, arguments, and any issue-source options).",
+  ),
   Command.withHandler(
     Effect.fnUntraced(function* () {
       const meta = yield* CurrentIssueSource

package/src/commands/agents/rm.ts

@@ -9,7 +9,9 @@ import {
 } from "../../Presets.ts"
 
 export const commandAgentsRm = Command.make("rm").pipe(
-  Command.withDescription("Remove a CLI agent preset"),
+  Command.withDescription(
+    "Remove an agent preset (select a preset to delete from your configuration).",
+  ),
   Command.withHandler(
     Effect.fnUntraced(function* () {
       const presets = yield* getAllCliAgentPresets

package/src/commands/agents.ts

@@ -12,11 +12,15 @@ const subcommands = Command.withSubcommands([
 ])
 
 export const commandAgents = Command.make("agents").pipe(
-  Command.withDescription("Manage CLI agent presets"),
+  Command.withDescription(
+    "Manage agent presets used to run tasks. Use 'ls' to inspect presets and 'add'/'edit' to configure agents, arguments, and any issue-source options.",
+  ),
   subcommands,
 )
 
 export const commandAgentsAlias = Command.make("a").pipe(
-  Command.withDescription("Alias for 'agents' command"),
+  Command.withDescription(
+    "Alias for 'agents' (manage agent presets used to run tasks).",
+  ),
   subcommands,
 )

package/src/commands/edit.ts

@@ -19,11 +19,15 @@ const handler = Command.withHandler(
 )
 
 export const commandEdit = Command.make("edit").pipe(
-  Command.withDescription("Open the prd.yml file in your editor"),
+  Command.withDescription(
+    "Open the selected project's .lalph/prd.yml in your editor.",
+  ),
   handler,
 )
 
 export const commandEditAlias = Command.make("e").pipe(
-  Command.withDescription("Alias for 'edit' command"),
+  Command.withDescription(
+    "Alias for 'edit' (open the selected project's .lalph/prd.yml in your editor).",
+  ),
   handler,
 )

package/src/commands/issue.ts

@@ -87,11 +87,13 @@ const handler = flow(
 )
 
 export const commandIssue = Command.make("issue").pipe(
-  Command.withDescription("Create a new issue in the selected issue source"),
+  Command.withDescription("Create a new issue in your editor."),
   handler,
 )
 
 export const commandIssueAlias = Command.make("i").pipe(
-  Command.withDescription("Alias for 'issue' command"),
+  Command.withDescription(
+    "Alias for 'issue' (create a new issue in your editor).",
+  ),
   handler,
 )

package/src/commands/plan/tasks.ts

@@ -15,14 +15,16 @@ const specificationPath = Argument.path("spec", {
   mustExist: true,
 }).pipe(
   Argument.withDescription(
-    "Path to the specification file to convert into tasks",
+    "Required. Path to an existing specification file to convert into tasks",
   ),
 )
 
 export const commandPlanTasks = Command.make("tasks", {
   specificationPath,
 }).pipe(
-  Command.withDescription("Convert a specification into tasks"),
+  Command.withDescription(
+    "Convert an existing specification file into PRD tasks (without re-running plan mode)",
+  ),
   Command.withHandler(
     Effect.fnUntraced(
       function* ({ specificationPath }) {

package/src/commands/plan.ts

@@ -12,24 +12,30 @@ import { agentTasker } from "../Agents/tasker.ts"
 import { commandPlanTasks } from "./plan/tasks.ts"
 import { Editor } from "../Editor.ts"
 import { getDefaultCliAgentPreset } from "../Presets.ts"
+import { ChildProcess } from "effect/unstable/process"
+import { parseBranch } from "../shared/git.ts"
 
 const dangerous = Flag.boolean("dangerous").pipe(
   Flag.withAlias("d"),
   Flag.withDescription(
-    "Enable dangerous mode (skip permission prompts) during plan generation",
+    "Skip permission prompts while generating the specification from your plan",
   ),
 )
 
 const withNewProject = Flag.boolean("new").pipe(
   Flag.withAlias("n"),
-  Flag.withDescription("Create a new project before starting plan mode"),
+  Flag.withDescription(
+    "Create a new project (via prompts) before starting plan mode",
+  ),
 )
 
 export const commandPlan = Command.make("plan", {
   dangerous,
   withNewProject,
 }).pipe(
-  Command.withDescription("Iterate on an issue plan and create PRD tasks"),
+  Command.withDescription(
+    "Open an editor to draft a plan; on save, generate a specification under --specs and then create PRD tasks from it. Use --new to create a project first; use --dangerous to skip permission prompts during spec generation.",
+  ),
   Command.withHandler(
     Effect.fnUntraced(function* ({ dangerous, withNewProject }) {
       const editor = yield* Editor
@@ -86,6 +92,13 @@ const plan = Effect.fnUntraced(
       Effect.mapError(() => new SpecNotFound()),
     )
 
+    if (Option.isSome(options.targetBranch)) {
+      yield* commitAndPushSpecification({
+        specsDirectory: options.specsDirectory,
+        targetBranch: options.targetBranch.value,
+      })
+    }
+
     yield* Effect.log("Converting specification into tasks")
 
     yield* agentTasker({
@@ -119,6 +132,50 @@ export class SpecNotFound extends Data.TaggedError("SpecNotFound") {
   readonly message = "The AI agent failed to produce a specification."
 }
 
+export class SpecGitError extends Data.TaggedError("SpecGitError")<{
+  readonly message: string
+}> {}
+
+const commitAndPushSpecification = Effect.fnUntraced(
+  function* (options: {
+    readonly specsDirectory: string
+    readonly targetBranch: string
+  }) {
+    const worktree = yield* Worktree
+    const pathService = yield* Path.Path
+
+    const absSpecsDirectory = pathService.join(
+      worktree.directory,
+      options.specsDirectory,
+    )
+
+    const git = (args: ReadonlyArray<string>) =>
+      ChildProcess.make("git", [...args], {
+        cwd: worktree.directory,
+        stdout: "inherit",
+        stderr: "inherit",
+      }).pipe(ChildProcess.exitCode)
+
+    const addCode = yield* git(["add", absSpecsDirectory])
+    if (addCode !== 0) {
+      return yield* new SpecGitError({
+        message: "Failed to stage specification changes.",
+      })
+    }
+
+    const commitCode = yield* git(["commit", "-m", "Update plan specification"])
+    if (commitCode !== 0) {
+      return yield* new SpecGitError({
+        message: "Failed to commit the generated specification changes.",
+      })
+    }
+
+    const parsed = parseBranch(options.targetBranch)
+    yield* git(["push", parsed.remote, `HEAD:${parsed.branch}`])
+  },
+  Effect.ignore({ log: "Warn" }),
+)
+
 const PlanDetails = Schema.fromJsonString(
   Schema.Struct({
     specification: Schema.String,

package/src/commands/projects/add.ts

@@ -4,7 +4,9 @@ import { CurrentIssueSource } from "../../CurrentIssueSource.ts"
 import { Settings } from "../../Settings.ts"
 
 export const commandProjectsAdd = Command.make("add").pipe(
-  Command.withDescription("Add a new project"),
+  Command.withDescription(
+    "Add a project and configure its execution settings (concurrency, target branch, git flow, review agent) and issue source settings.",
+  ),
   Command.withHandler(() => addOrUpdateProject()),
   Command.provide(Settings.layer),
   Command.provide(CurrentIssueSource.layer),

package/src/commands/projects/edit.ts

@@ -9,7 +9,9 @@ import { Settings } from "../../Settings.ts"
 import { CurrentIssueSource } from "../../CurrentIssueSource.ts"
 
 export const commandProjectsEdit = Command.make("edit").pipe(
-  Command.withDescription("Modify a project"),
+  Command.withDescription(
+    "Edit a project's execution settings (concurrency, target branch, git flow, review agent) and issue source settings.",
+  ),
   Command.withHandler(
     Effect.fnUntraced(function* () {
       const projects = yield* getAllProjects

package/src/commands/projects/ls.ts

@@ -6,7 +6,9 @@ import { getAllProjects } from "../../Projects.ts"
 import { Settings } from "../../Settings.ts"
 
 export const commandProjectsLs = Command.make("ls").pipe(
-  Command.withDescription("List all configured projects and their settings"),
+  Command.withDescription(
+    "List configured projects and how they run (enabled state, concurrency, branch, git flow, review agent).",
+  ),
   Command.withHandler(
     Effect.fnUntraced(function* () {
       const meta = yield* CurrentIssueSource

package/src/commands/projects/rm.ts

@@ -5,7 +5,9 @@ import { Settings } from "../../Settings.ts"
 import { CurrentIssueSource } from "../../CurrentIssueSource.ts"
 
 export const commandProjectsRm = Command.make("rm").pipe(
-  Command.withDescription("Remove a project"),
+  Command.withDescription(
+    "Remove a project from the configured list and delete its stored state under .lalph/projects.",
+  ),
   Command.withHandler(
     Effect.fnUntraced(function* () {
       const fs = yield* FileSystem.FileSystem

package/src/commands/projects/toggle.ts

@@ -5,7 +5,9 @@ import { Settings } from "../../Settings.ts"
 import { Project } from "../../domain/Project.ts"
 
 export const commandProjectsToggle = Command.make("toggle").pipe(
-  Command.withDescription("Enable or disable projects"),
+  Command.withDescription(
+    "Enable or disable configured projects for lalph runs.",
+  ),
   Command.withHandler(
     Effect.fnUntraced(function* () {
       const projects = yield* getAllProjects

package/src/commands/projects.ts

@@ -14,11 +14,13 @@ const subcommands = Command.withSubcommands([
 ])
 
 export const commandProjects = Command.make("projects").pipe(
-  Command.withDescription("Manage projects"),
+  Command.withDescription(
+    "Manage projects and their execution settings (enabled state, concurrency, target branch, git flow, review agent). Use 'ls' to inspect and 'add', 'edit', or 'toggle' to configure.",
+  ),
   subcommands,
 )
 
 export const commandProjectsAlias = Command.make("p").pipe(
-  Command.withDescription("Alias for 'projects' command"),
+  Command.withDescription("Alias for 'projects'."),
   subcommands,
 )

package/src/commands/root.ts

@@ -323,14 +323,16 @@ const runProject = Effect.fnUntraced(
 // Command
 
 const iterations = Flag.integer("iterations").pipe(
-  Flag.withDescription("Number of iterations to run, defaults to unlimited"),
+  Flag.withDescription(
+    "Limit how many task iterations run per enabled project (default: unlimited). Use -i 1 to run a single iteration and exit.",
+  ),
   Flag.withAlias("i"),
   Flag.withDefault(Number.POSITIVE_INFINITY),
 )
 
 const maxIterationMinutes = Flag.integer("max-minutes").pipe(
   Flag.withDescription(
-    "Maximum number of minutes to allow an iteration to run. Defaults to 90 minutes. Env variable: LALPH_MAX_MINUTES",
+    "Timeout an iteration if execution (and review, if enabled) exceeds this many minutes (default: LALPH_MAX_MINUTES or 90).",
   ),
   Flag.withFallbackConfig(Config.int("LALPH_MAX_MINUTES")),
   Flag.withDefault(90),
@@ -338,7 +340,7 @@ const maxIterationMinutes = Flag.integer("max-minutes").pipe(
 
 const stallMinutes = Flag.integer("stall-minutes").pipe(
   Flag.withDescription(
-    "If no activity occurs for this many minutes, the iteration will be stopped. Defaults to 5 minutes. Env variable: LALPH_STALL_MINUTES",
+    "Fail an iteration if the agent stops responding for this many minutes (default: LALPH_STALL_MINUTES or 5).",
   ),
   Flag.withFallbackConfig(Config.int("LALPH_STALL_MINUTES")),
   Flag.withDefault(5),
@@ -346,7 +348,7 @@ const stallMinutes = Flag.integer("stall-minutes").pipe(
 
 const specsDirectory = Flag.directory("specs").pipe(
   Flag.withDescription(
-    "Directory to store plan specifications. Env variable: LALPH_SPECS",
+    "Directory where plan specs are written and read (default: LALPH_SPECS or .specs).",
   ),
   Flag.withAlias("s"),
   Flag.withFallbackConfig(Config.string("LALPH_SPECS")),
@@ -354,7 +356,9 @@ const specsDirectory = Flag.directory("specs").pipe(
 )
 
 const verbose = Flag.boolean("verbose").pipe(
-  Flag.withDescription("Enable verbose logging"),
+  Flag.withDescription(
+    "Increase log output for debugging. Use -v when you need detailed logs.",
+  ),
   Flag.withAlias("v"),
 )
 
@@ -365,6 +369,9 @@ export const commandRoot = Command.make("lalph", {
   specsDirectory,
   verbose,
 }).pipe(
+  Command.withDescription(
+    "Run the task loop across all enabled projects in parallel: pull issues from the current issue source and execute them with your configured agent preset(s). Use --iterations for a bounded run, and configure per-project concurrency via lalph projects edit.",
+  ),
   Command.withHandler(
     Effect.fnUntraced(
       function* ({

package/src/commands/sh.ts

@@ -6,7 +6,9 @@ import { Worktree } from "../Worktree.ts"
 import { layerProjectIdPrompt } from "../Projects.ts"
 
 export const commandSh = Command.make("sh").pipe(
-  Command.withDescription("Enter an interactive shell in the worktree"),
+  Command.withDescription(
+    "Launch an interactive shell in the active project's worktree.",
+  ),
   Command.withHandler(
     Effect.fnUntraced(
       function* () {

package/src/commands/source.ts

@@ -3,7 +3,9 @@ import { selectIssueSource } from "../CurrentIssueSource.ts"
 import { Settings } from "../Settings.ts"
 
 export const commandSource = Command.make("source").pipe(
-  Command.withDescription("Select the issue source to use"),
+  Command.withDescription(
+    "Select the issue source to use (e.g. GitHub Issues or Linear). This applies to all projects.",
+  ),
   Command.withHandler(() => selectIssueSource),
   Command.provide(Settings.layer),
 )