sdd-cli 0.1.16 → 0.1.18

package/README.md

@@ -156,6 +156,7 @@ Use `--questions` when you want the manual question-by-question flow.
 - `sdd-cli quickstart` -- one-command demo flow with built-in examples
 - `sdd-cli init` -- create SDD workspace and config
 - `sdd-cli list` -- list flows, router flows, templates, prompt packs, and projects
+- `sdd-cli status --next` -- show current project state and exact next command
 - `sdd-cli doctor` -- validate completeness and consistency
 
 ### Router
@@ -192,6 +193,9 @@ Use `--questions` when you want the manual question-by-question flow.
 - `--parallel` -- generate in parallel
 - `--questions` -- use manual question-driven discovery flow
 - `--non-interactive` -- run without confirmations (script/CI friendly)
+- `--beginner` -- show extra step-by-step explanations during hello autopilot
+- `--dry-run` -- preview autopilot stages without writing artifacts
+- `--from-step` -- resume autopilot from `create|plan|start|test|finish`
 - `--alias sdd` -- optional alias to run as `sdd`
 
 ## Beginner quickstart
@@ -209,6 +213,10 @@ sdd-cli hello "I want a simple booking system for appointments"
 5) Check output in:
 `<workspace>/<project>/requirements/done/<REQ-ID>/`
 
+For a full onboarding walkthrough, see:
+- `docs/FIRST_15_MINUTES.md`
+- `examples/transcripts/FIRST_15_MINUTES.md`
+
 ## Recovery quick commands
 
 - Continue an existing project:

package/dist/cli.js

@@ -45,6 +45,7 @@ const init_1 = require("./commands/init");
 const route_1 = require("./commands/route");
 const doctor_1 = require("./commands/doctor");
 const quickstart_1 = require("./commands/quickstart");
+const status_1 = require("./commands/status");
 const paths_1 = require("./paths");
 const flags_1 = require("./context/flags");
 const prompt_1 = require("./ui/prompt");
@@ -68,6 +69,7 @@ program
     .option("--parallel", "Generate in parallel when supported")
     .option("--non-interactive", "Run with defaults and without prompt confirmations")
     .option("--dry-run", "Preview autopilot steps without writing artifacts")
+    .option("--beginner", "Enable extra step-by-step guidance in hello flow")
     .option("--from-step <step>", "Resume or start autopilot from step: create|plan|start|test|finish")
     .option("--project <name>", "Select or name the project")
     .option("--output <path>", "Override workspace output root");
@@ -79,6 +81,7 @@ program.hook("preAction", (thisCommand, actionCommand) => {
         parallel: Boolean(opts.parallel),
         nonInteractive: Boolean(opts.nonInteractive),
         dryRun: Boolean(opts.dryRun),
+        beginner: Boolean(opts.beginner),
         fromStep: typeof opts.fromStep === "string" ? opts.fromStep : undefined,
         project: typeof opts.project === "string" ? opts.project : undefined,
         output: typeof opts.output === "string" ? opts.output : undefined
@@ -111,6 +114,11 @@ program
     const { runList } = await Promise.resolve().then(() => __importStar(require("./commands/list")));
     runList();
 });
+program
+    .command("status")
+    .description("Show project requirement counts and next recommended command")
+    .option("--next", "Print exact next command to run")
+    .action((options) => (0, status_1.runStatus)(Boolean(options.next)));
 const req = program.command("req").description("Requirement lifecycle commands");
 req
     .command("create")

package/dist/commands/hello.js

@@ -23,6 +23,12 @@ function printWhy(message) {
 function printRecoveryNext(project, step, hint) {
     console.log(`Next command: sdd-cli --project "${project}" --from-step ${step} hello "${hint}"`);
 }
+function printBeginnerTip(enabled, tip) {
+    if (!enabled) {
+        return;
+    }
+    console.log(`  [Beginner] ${tip}`);
+}
 function deriveProjectName(input, flow) {
     const seed = input
         .trim()
@@ -107,8 +113,12 @@ async function runHello(input, runQuestions) {
     const shouldRunQuestions = runQuestions === true;
     const autoGuidedMode = !shouldRunQuestions && (runtimeFlags.nonInteractive || hasDirectIntent);
     const dryRun = runtimeFlags.dryRun;
+    const beginnerMode = runtimeFlags.beginner;
     console.log("Hello from sdd-cli.");
     console.log(`Workspace: ${workspace.root}`);
+    if (beginnerMode) {
+        printBeginnerTip(true, "I will explain each step and tell you what happens next.");
+    }
     if (autoGuidedMode) {
         printWhy("Auto-guided mode active: using current workspace defaults.");
     }
@@ -193,6 +203,7 @@ async function runHello(input, runQuestions) {
     console.log(`Detected intent: ${intent.intent} -> ${intent.flow}`);
     printStep("Step 1/7", "Intent detected");
     printWhy("I classified your goal and selected the best starting flow.");
+    printBeginnerTip(beginnerMode, "Intent helps me pick the right workflow and defaults.");
     const showRoute = runQuestions === true ? await (0, prompt_1.confirm)("View route details now? (y/n) ") : false;
     if (showRoute && runQuestions === true) {
         (0, route_1.runRoute)(text);
@@ -202,6 +213,7 @@ async function runHello(input, runQuestions) {
     }
     printStep("Step 2/7", "Requirement setup");
     printWhy("I will gather enough context to generate a valid first draft.");
+    printBeginnerTip(beginnerMode, "A requirement draft defines scope, acceptance criteria, and constraints.");
     if (shouldRunQuestions) {
         const packs = (0, prompt_packs_1.loadPromptPacks)();
         const packIds = intent_1.FLOW_PROMPT_PACKS[intent.flow] ?? [];
@@ -277,6 +289,7 @@ async function runHello(input, runQuestions) {
         const stepIndex = autopilot_checkpoint_1.AUTOPILOT_STEPS.indexOf(startStep);
         if (dryRun) {
             printWhy("Dry run active: previewing autopilot plan without writing files.");
+            printBeginnerTip(beginnerMode, "Dry run is safe: it shows plan only and does not change files.");
             for (let i = stepIndex; i < autopilot_checkpoint_1.AUTOPILOT_STEPS.length; i += 1) {
                 const step = autopilot_checkpoint_1.AUTOPILOT_STEPS[i];
                 console.log(`Would run step: ${step}`);
@@ -289,6 +302,7 @@ async function runHello(input, runQuestions) {
             if (step === "create") {
                 printStep("Step 3/7", "Creating requirement draft automatically");
                 printWhy("This creates your baseline scope, acceptance criteria, and NFRs.");
+                printBeginnerTip(beginnerMode, "After this, your requirement is ready for planning artifacts.");
                 const created = await (0, req_create_1.runReqCreate)(draft, { autofill: true });
                 if (!created) {
                     console.log("Autopilot stopped at requirement creation.");
@@ -300,6 +314,7 @@ async function runHello(input, runQuestions) {
             if (step === "plan") {
                 printStep("Step 4/7", `Planning requirement ${reqId}`);
                 printWhy("I am generating functional, technical, architecture, and test artifacts.");
+                printBeginnerTip(beginnerMode, "Planning creates the blueprint before implementation.");
                 const planned = await (0, req_plan_1.runReqPlan)({
                     projectName: activeProject,
                     reqId,
@@ -315,6 +330,7 @@ async function runHello(input, runQuestions) {
             if (step === "start") {
                 printStep("Step 5/7", `Preparing implementation plan for ${reqId}`);
                 printWhy("This stage defines milestones, tasks, quality thresholds, and decisions.");
+                printBeginnerTip(beginnerMode, "Start phase prepares execution details and quality guardrails.");
                 const started = await (0, req_start_1.runReqStart)({
                     projectName: activeProject,
                     reqId,
@@ -330,6 +346,7 @@ async function runHello(input, runQuestions) {
             if (step === "test") {
                 printStep("Step 6/7", `Updating test plan for ${reqId}`);
                 printWhy("I am ensuring critical paths, edge cases, and regression tests are documented.");
+                printBeginnerTip(beginnerMode, "Testing focus reduces regressions before delivery.");
                 const tested = await (0, test_plan_1.runTestPlan)({
                     projectName: activeProject,
                     reqId,
@@ -345,6 +362,7 @@ async function runHello(input, runQuestions) {
             if (step === "finish") {
                 printStep("Step 7/7", `Finalizing requirement ${reqId}`);
                 printWhy("I will move artifacts to done state and generate project-level summary files.");
+                printBeginnerTip(beginnerMode, "Finish locks outputs and leaves a reusable delivery record.");
                 const finished = await (0, req_finish_1.runReqFinish)({
                     projectName: activeProject,
                     reqId,

package/dist/commands/status.d.ts

@@ -0,0 +1 @@
+export declare function runStatus(showNext?: boolean): void;

package/dist/commands/status.js

@@ -0,0 +1,97 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runStatus = runStatus;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const flags_1 = require("../context/flags");
+const index_1 = require("../workspace/index");
+const REQUIREMENT_STATUSES = ["backlog", "wip", "in-progress", "done", "archived"];
+function listRequirementIds(projectRoot, status) {
+    const dir = path_1.default.join(projectRoot, "requirements", status);
+    if (!fs_1.default.existsSync(dir)) {
+        return [];
+    }
+    return fs_1.default
+        .readdirSync(dir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort();
+}
+function latestId(ids) {
+    if (ids.length === 0) {
+        return null;
+    }
+    return ids[ids.length - 1];
+}
+function recommendNext(projectName, counts, ids) {
+    const nextInProgress = latestId(ids["in-progress"]);
+    if (nextInProgress) {
+        return `sdd-cli --project "${projectName}" req finish  # then enter ${nextInProgress} when prompted`;
+    }
+    const nextWip = latestId(ids.wip);
+    if (nextWip) {
+        return `sdd-cli --project "${projectName}" req start  # then enter ${nextWip} when prompted`;
+    }
+    const nextBacklog = latestId(ids.backlog);
+    if (nextBacklog) {
+        return `sdd-cli --project "${projectName}" req plan  # then enter ${nextBacklog} when prompted`;
+    }
+    if (counts.done > 0 && counts.archived === 0) {
+        return `sdd-cli --project "${projectName}" hello "start next requirement"`;
+    }
+    return `sdd-cli --project "${projectName}" hello "continue"`;
+}
+function runStatus(showNext) {
+    const workspace = (0, index_1.getWorkspaceInfo)();
+    (0, index_1.ensureWorkspace)(workspace);
+    const projects = (0, index_1.listProjects)(workspace);
+    const flags = (0, flags_1.getFlags)();
+    const selectedName = flags.project && flags.project.trim().length > 0 ? flags.project.trim() : projects[0]?.name;
+    if (!selectedName) {
+        console.log("No projects found.");
+        if (showNext) {
+            console.log('Next command: sdd-cli quickstart --example saas');
+        }
+        return;
+    }
+    let project;
+    try {
+        project = (0, index_1.getProjectInfo)(workspace, selectedName);
+    }
+    catch (error) {
+        console.log(error.message);
+        return;
+    }
+    if (!fs_1.default.existsSync(project.root)) {
+        console.log("No projects found.");
+        if (showNext) {
+            console.log('Next command: sdd-cli quickstart --example saas');
+        }
+        return;
+    }
+    const ids = {
+        backlog: listRequirementIds(project.root, "backlog"),
+        wip: listRequirementIds(project.root, "wip"),
+        "in-progress": listRequirementIds(project.root, "in-progress"),
+        done: listRequirementIds(project.root, "done"),
+        archived: listRequirementIds(project.root, "archived")
+    };
+    const counts = {
+        backlog: ids.backlog.length,
+        wip: ids.wip.length,
+        "in-progress": ids["in-progress"].length,
+        done: ids.done.length,
+        archived: ids.archived.length
+    };
+    console.log(`Project: ${project.name}`);
+    REQUIREMENT_STATUSES.forEach((status) => {
+        console.log(`- ${status}: ${counts[status]}`);
+    });
+    if (showNext) {
+        const recommendation = recommendNext(project.name, counts, ids);
+        console.log(`Next command: ${recommendation}`);
+    }
+}

package/dist/context/flags.d.ts

@@ -4,6 +4,7 @@ export type RuntimeFlags = {
     parallel: boolean;
     nonInteractive: boolean;
     dryRun: boolean;
+    beginner: boolean;
     fromStep?: string;
     project?: string;
     output?: string;

package/dist/context/flags.js

@@ -8,6 +8,7 @@ const flags = {
     parallel: false,
     nonInteractive: false,
     dryRun: false,
+    beginner: false,
     fromStep: undefined,
     project: undefined,
     output: undefined
@@ -28,6 +29,9 @@ function setFlags(next) {
     if ("dryRun" in next) {
         flags.dryRun = Boolean(next.dryRun);
     }
+    if ("beginner" in next) {
+        flags.beginner = Boolean(next.beginner);
+    }
     if ("fromStep" in next) {
         flags.fromStep = typeof next.fromStep === "string" ? next.fromStep : undefined;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-cli",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "SDD-first, AI-native CLI for end-to-end delivery.",
   "homepage": "https://github.com/jdsalasca/sdd-tool#readme",
   "repository": {