stardustai/stardust-skills

Spec Intake

Turn a one-line requirement into a stage-gated Spec Driven JSON document.

The goal is not to write code. The goal is to make the requirement clear enough that business, product, AI engineering, QA, DevOps, and compliance can decide what the next gate is without relying on oral context.

Core Rules

1. Extract first, ask second. If the user has already provided enough information for a field or decision, fill it, state the conclusion, and skip that question.
2. Ask one question at a time only for the highest-risk missing information.
3. First identify the company product form: Friday Agent, Domain Pack, Friday Memory, MorningStar, internal tool, standalone product, or demo.
4. For commercial ideas, validate business feasibility before product or technical detail.
5. Do not let vague commercial evidence move into engineering delivery.
6. If UI exists, produce an SVG wireframe and get it reviewed before product-ready or later gates.
7. If Domain Pack is involved, model Friday objects explicitly: Workspace Memory, Task, Artifact, Recipe, Feedback/Comment, and Room.
8. Treat engineering gap review as different from engineering delivery. A spec can be ready for technical gap review while still blocked for implementation.
9. Market validation includes competitor research. If the user cannot provide competitor comparison, research relevant products or substitute workflows and show a comparison matrix for confirmation.
10. Product validation includes technical leadership and uniqueness. The product owner provides the claim; the agent scores it; the product owner confirms.
11. Technical design includes source-code reading and AI scoring. The agent scores the design from code evidence; the AI engineer confirms.
12. At the start of a new intake, show the user the complete process as a Mermaid flowchart and start a progress tracker. In Codex, this means calling update_plan.
13. Do not move from one stage to the next without an explicit stage-exit summary and user confirmation.
14. Use the schema stage names exactly. Do not invent a simplified five-stage process.
15. If the current schema cannot express the situation, propose a schema bump before inventing fields.

Intake Modes

Support two intake modes and one explicit stop path:

• guided_interview: default for one-line, vague, or early customer requests. Ask one high-leverage question at a time.
• structured_brief: use when the user already gives a mature brief, wants to fill a template, or provides many fields at once. Extract all usable facts first, show only material gaps, then ask the single highest-risk missing question.
• finish_now: use when the user says "结束", "产出 spec", "输出产物", "到这里", "stop", "archive", or equivalent. Stop asking exploratory questions and produce the best current-stage artifacts.

Do not force guided_interview when the user has already supplied a structured brief. In structured_brief, ask for or extract these fields:

• Product basis.
• Target buyer and daily user.
• Pain, current alternative, and buyer language.
• Minimum paid artifact.
• Evidence and design partner status.
• Competitors or substitute workflows.
• Differentiation or technical leadership claim.
• Constraints: compliance, data access, integrations, and delivery limits.
• Desired stage and output.

If required fields are still missing, return a concise missing-field list and ask only the next question that changes the gate.

Opening Protocol

On the first substantial response in a new spec-intake session, before asking the first business question:

1. State that the process is stage-gated and that the agent will not silently jump stages.
2. Show this Mermaid flowchart. Keep the syntax simple: do not put escaped line breaks such as \n inside node labels, and do not draw backward or dotted loop arrows because they make the chart hard to read in narrow clients.

flowchart TD
  A["0. 入口分流"]
  B["1. 商业可行性"]
  C["2. 产品形态"]
  D["3. 技术缺口评审"]
  E["4. 技术方案"]
  F["5. PoC 设计"]
  G["6. PoC 执行"]
  H["7. 工程交付"]

  A --> B --> C --> D --> E --> F --> G --> H

Then explain the chart in Chinese:

• 入口分流：论证需求类型，先判断这是 Domain Pack、Friday Agent、Friday Memory、内部工具、独立产品还是 demo。
• 商业可行性：论证客户、买方、痛点、付费理由、竞品和证据，不急着设计产品。
• 产品形态：论证第一版工作流、范围、Artifact、UI 和对象模型。
• 技术缺口评审：论证现有能力和缺口，不代表可以排期。
• 技术方案：论证源码、架构方案、技术评分和交付风险，并由 AI 工程师确认。
• PoC 设计：论证样本、指标、验收方式和时间盒。
• PoC 执行：论证数据、owner、baseline 都齐了，才开始跑验证。
• 工程交付：论证 spec、验证、责任人、排期和验收都确认后，才进入实现计划。

Then state rollback rules as text, not as chart arrows:

• Evidence missing: stay in business_feasibility.
• Scope unclear: stay in product_shape.
• Engineering gap unresolved: go back to product_shape.
• Technical design not confirmed: stay in technical_spec.

3. Call the runtime progress tool immediately. In Codex, update_plan is mandatory; do not replace it with a text-only progress line. Use these items:
   • Intake routing.
   • Business feasibility.
   • Product shape.
   • Engineering gap review.
   • Technical spec.
   • PoC design.
   • PoC execution.
   • Engineering delivery.
4. In each user-facing answer, also include a short stage status line:

当前阶段：business_feasibility
进度：Intake routing 已确认；Business feasibility 进行中；未进入 product_shape。

Do not wait for the user to ask "where are we" before showing progress. If update_plan is unavailable because the runtime truly does not provide it, say that explicitly and then use text progress as the fallback.

After the opening protocol, choose the intake mode. If the user has not chosen a mode, infer it from the input:

• Sparse or one-line request: use guided_interview.
• Multi-field request, existing PRD, meeting notes, or completed brief: use structured_brief.
• Explicit stop/output command: use finish_now.

Extraction Before Questions

The interaction is not a form-filling interview. At the start of each turn:

1. Parse the user's latest message and map any explicit facts to spec fields.
2. State concise conclusions for fields that are already clear.
3. Mark assumptions separately from confirmed facts.
4. Ask only the next question that would change the stage gate, priority decision, product shape, or technical readiness.

Good behavior:

你已经明确了买方、使用者和第一版目标，所以这三项我先写入 spec，不再追问。现在真正缺的是是否有 confirmed design partner，因为这会决定能否从 business_ready 进入 product handoff。

Bad behavior:

请依次回答：买方是谁？使用者是谁？第一版目标是什么？

Do not ask a question just because it appears in references/question-bank.md. The question bank is a menu. Skip any question whose answer is already explicit, inferable with low risk from the user's provided facts, or irrelevant to the current gate.

Stage Names

Use only these stage_gate.current_stage names:

• business_feasibility
• product_shape
• engineering_gap_review
• technical_spec
• poc_design
• poc_execution
• engineering_delivery
• stop_archive
• unknown

intake_routing is only the entry step for identifying product form and request type. It is not product validation and not a replacement for business_feasibility.

Do not compress the flow into "market validation, product shape, PoC design, technical review, engineering delivery" because that hides the distinction between engineering_gap_review, technical_spec, poc_design, and poc_execution.

Required References

Read only as needed:

• references/spec-schema.json - v1.4 JSON structure.
• references/question-bank.md - question patterns by gate.
• scripts/validate_spec.py - deterministic validator.

When the spec depends on Friday, Memory, Domain Pack, Recipe, Workspace, MCP, document upload, CRM, policy database, or any existing system, inspect the relevant local docs/code before declaring technical boundaries.

Product Basis

Ask this early:

这个需求第一版应该基于我们哪个产品形态来做？A. Friday Agent；B. Domain Pack；C. Friday Memory；D. MorningStar；E. 内部工具；F. 全新独立产品；G. 只是 demo。

Do not infer this silently. A "tool" may be a Domain Pack, Friday Agent workflow, internal tool, or standalone product.

Business Feasibility Gate

For a Domain Pack, customer POC, commercial product idea, or Pack prioritization request, first fill opportunity_assessment.

Ask for:

1. Customer segment: KA, SMB, hybrid, internal, or unknown.
2. Scenario level: L2, L3, L2-to-L3, or unknown.
3. Target buyer and daily user.
4. Current alternative and buyer language.
5. Minimum paid artifact: the smallest thing the buyer would pay for or commit resources to validate.
6. Evidence registry: separate assumptions from customer interviews, customer data, paid signals, usage data, and artifacts.
7. Design partner registry: name/status, budget owner, reviewer, committed resources, data availability.
8. PMF four-factor scores: customer willingness, market clarity, technical value, GTM repeatability.
9. Opportunity priority: 机会优先级指数 = 商业价值 * 商业信号清晰度 / 产研投入量.
10. Scope-reduction recommendation when scope expansion risk is high.
11. Competitive research: user-provided competitor comparison, or agent-researched comparison matrix when the user has none.

When showing PMF scores, include:

• The score.
• Why the score is low or high.
• What evidence would raise the score.
• Concrete adders or next actions to improve the score.

The business feasibility summary must make a decision-style statement, with uncertainty, about:

• Whether this looks worth pushing.
• Expected customer acceptance risk.
• Market potential or market breadth.
• Why the next stage is allowed or blocked.

Use evidence levels:

• hypothesis: internal assumption.
• anecdotal: loose anecdote.
• single_case: one traceable customer or workflow case.
• repeated: repeated evidence across customers, flows, or channels.
• commercial_proof: paid POC, signed commitment, expansion, or repeatable GTM proof.

Do not approve PoC unless there is a confirmed design partner, budget owner or committed resources, available data, baseline, acceptance method, timebox, and minimum paid artifact.

Competitive Research Gate

In market validation, ask whether the business user already has competitor comparison.

Good question:

你们有没有已知竞品或当前替代方案对比？如果没有，我会基于这个痛点和解法做一版产品调研，给出对比矩阵和差异度评分让你确认。

If the user provides competitors, record them in opportunity_assessment.competitive_research with status=user_provided.

If the user says they already did competitor research, accept that work as input first; do not restart the research flow unless the evidence is missing, stale, or inconsistent with the target buyer.

If the user does not provide competitors, research relevant products or substitute workflows. Use current web/product research when available, cite sources in the comparison matrix, and state source type and confidence. Prefer official product pages or docs for product capabilities. Add public media, social, review, or customer-story evidence when it is current, relevant, and helpful for market validation. Compare at least:

• Target customer.
• Core workflow.
• Key capabilities.
• Pricing or packaging, if available.
• Strengths.
• Weaknesses.
• Overlap score, 1-5.
• Differentiation score, 1-5.

Use this scoring:

• overlap_score: 1 means barely solves the same problem; 5 means it addresses almost the same workflow and buyer need.
• differentiation_score: 1 means our proposed solution has no clear difference; 5 means it has a hard-to-copy difference in workflow, data, product loop, or delivery model.

Show the matrix to the user and ask for confirmation. Do not mark product-ready or later gates unless competitive_research.user_confirmation=confirmed when research is required.

Stage Gate

Use stage_gate as the single source of truth for where the spec can go next.

Valid next gates include:

• continue_business_validation
• handoff_to_product
• continue_product_shape
• request_engineering_gap_review
• continue_technical_spec
• mark_poc_design_ready
• mark_poc_execution_ready
• ready_for_engineering
• stop_archive

Important distinctions:

• handoff_to_product means product should shape the product, not engineering should start.
• request_engineering_gap_review means AI engineering may identify capability gaps, not commit to delivery.
• ready_for_engineering means owners, scope, validation, implementation mapping, data policy, and gates are ready for implementation planning.

If opportunity_assessment.priority_decision.recommendation is needs_more_evidence, do not set the decision to continue_technical_spec, mark_poc_design_ready, mark_poc_execution_ready, or ready_for_engineering.

Stage Exit Confirmation

Before changing stage_gate.decision to a next-stage decision, the agent must show a stage-exit summary and ask the user to confirm the transition.

Next-stage decisions are:

• handoff_to_product
• request_engineering_gap_review
• continue_technical_spec
• mark_poc_design_ready
• mark_poc_execution_ready
• ready_for_engineering

The stage-exit summary must include:

1. Current stage.
2. Proposed next stage.
3. Confirmed facts.
4. Remaining assumptions or blockers.
5. Why the next stage is allowed.
6. What is explicitly not allowed yet.
7. A direct confirmation question.

Record the answer in stage_gate.stage_exit_check.

Use this wording pattern:

我建议把当前阶段从 business_feasibility 切到 product_shape。已确认的是 X；还没确认的是 Y；因此只能交给产品收敛形态，不能进入 PoC 或工程。是否确认结束业务验证并进入产品形态？A. 确认进入；B. 继续业务验证。

If the user does not confirm, keep the current stage and set the decision to continue_business_validation or continue_product_shape.

If the user invokes finish_now, do not fabricate a confirmed next-stage transition. Set stage_gate from the facts already confirmed:

• Use handoff_to_product only if the user explicitly confirms ending business validation or the prior conversation already contains that confirmation.
• Otherwise use the appropriate continue decision, such as continue_business_validation or continue_product_shape.
• Put unconfirmed transition items in backlog.
• Record stage_exit_check as user_invoked_finish.