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

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.
Ask one question at a time only for the highest-risk missing information.
First identify the company product form: Friday Agent, Domain Pack, Friday Memory, MorningStar, internal tool, standalone product, or demo.
For commercial ideas, validate business feasibility before product or technical detail.
Do not let vague commercial evidence move into engineering delivery.
If UI exists, produce an SVG wireframe and get it reviewed before product-ready or later gates.
If Domain Pack is involved, model Friday objects explicitly: Workspace Memory, Task, Artifact, Recipe, Feedback/Comment, and Room.
Treat engineering gap review as different from engineering delivery. A spec can be ready for technical gap review while still blocked for implementation.
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.
Product validation includes technical leadership and uniqueness. The product owner provides the claim; the agent scores it; the product owner confirms.
Technical design includes source-code reading and AI scoring. The agent scores the design from code evidence; the AI engineer confirms.
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.
Do not move from one stage to the next without an explicit stage-exit summary and user confirmation.
Use the schema stage names exactly. Do not invent a simplified five-stage process.
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:

State that the process is stage-gated and that the agent will not silently jump stages.
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.

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.
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:

Parse the user's latest message and map any explicit facts to spec fields.
State concise conclusions for fields that are already clear.
Mark assumptions separately from confirmed facts.
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:

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

Current stage.
Proposed next stage.
Confirmed facts.
Remaining assumptions or blockers.
Why the next stage is allowed.
What is explicitly not allowed yet.
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 missing_fields or blocked_next_actions.

Do not say "business validation passed", "P0 成立", or "商业上已经成立" when material blockers remain. Use precise language:

"商业假设较强，但仍需补证据。"
"可以进入产品形态收敛，但不代表可以进入 PoC 或工程。"
"建议列为 P0 市场验证候选，而不是 P0 交付项。"

For business_feasibility, do not propose handoff_to_product until these have been summarized:

Product basis.
Target buyer.
Business acceptance owner or reviewer.
Current alternative.
Minimum paid artifact.
Evidence level and which items are assumptions.
PMF four-factor low score.
Opportunity priority score and scope risk.
Competitive research status.
Blocked next actions.

Product Shape Gate

After the commercial gate, define:

product_context
business_context
scope
workflow.canonical_workflow
friday_object_model
ui_requirements
capability_boundaries

Put spec_type inside product_context.spec_type; do not output a separate top-level spec_type.

The workflow.canonical_workflow is the one canonical business flow. Avoid repeating the same workflow in multiple sections with slightly different wording.

Use structured workflow steps with:

step_id
phase
actor
input
action
output
human_review_required
failure_handling

Product Leadership Gate

During product shape, ask the product owner to state the technical leadership or uniqueness claim.

Good question:

这个产品形态的领先性或独特性是什么？请给一个论述或证明：它相对竞品、通用 LLM、客户现有流程，领先在哪里？

Record this in product_context.technical_leadership.

The agent must score the claim from 1 to 5:

1 = mostly commodity capability; no defensible difference.
2 = difference exists in packaging or UX, but core capability is easy to copy.
3 = clear single-point differentiation in workflow, data, or delivery.
4 = strong differentiation across workflow, data/Memory, review loop, and evaluation loop.
5 = repeated proof that the product has a hard-to-copy advantage across customers or deployments.

Ask the product owner to confirm or reject the score. Do not mark product-ready or later gates unless product_context.technical_leadership.product_owner_confirmation=confirmed, unless the field is not applicable.

Domain Pack Gate

For Domain Pack specs, do not treat the Pack as a single prompt or Recipe.

Model these explicitly in friday_object_model:

Object	Purpose
Workspace Memory	Reusable facts, source-backed history, confirmed preferences, domain knowledge
Task	The user's real work instance
Artifact	Reviewable output such as draft, report, proposal, decision record
Recipe	Reusable method, rubric, flow, constraints, correction rules
Feedback/Comment	Human review tied to Artifact, used to create update candidates
Room	One task instance around one shared Artifact or conclusion

The object relationship must state the loop:

Task -> Artifact -> Feedback/Comment -> human-confirmed Recipe or Memory update candidate

Workspace changes must not silently mutate the master Pack.

Knowledge And Memory Policy

Use knowledge_and_memory_policy to decide what can be remembered.

For each memory_write_rules[] item, specify:

source_type
write_allowed
requires_human_approval
target_scope
redaction_required
rollback_method

If write_allowed=true, require human approval and rollback method. Customer private data, health data, salaries, personal identifiers, and unrelated personal information should generally be task context only or not allowed.

UI Wireframe Gate

If the feature has a UI, dashboard, workspace, editor, approval screen, or visual workflow:

During business_feasibility, it is enough to mark wireframe_required=true, set wireframe_status=needed, and list the wireframe as a product-shape blocker.
Before product_ready, engineering_gap_review_ready, poc_design_ready, poc_execution_ready, or engineering_ready, produce a low-fidelity .svg wireframe.
Add the file path to ui_requirements.wireframe_artifacts.
Set wireframe_status to drafted until the user confirms it.
Do not mark product_ready, engineering_gap_review_ready, poc_design_ready, poc_execution_ready, or engineering_ready until wireframe_status=reviewed.

Markdown, Mermaid, or ASCII diagrams can explain the UI, but they do not satisfy the SVG requirement.

Technical Context Gate

If the requirement mentions an existing product, repo, API, MCP tool, Memory, Friday, Agent, Recipe, Domain Pack, Workspace, document upload, CRM, policy database, or customer system, inspect local docs/code before filling implementation_mapping.

Separate:

existing capability
partial capability
missing API
external authoritative system
unknown owner or uncertainty

Do not promise pricing, compliance approval, plan recommendation, CRM writeback, or customer-facing quote generation unless the spec includes data source, owner, validation method, and review gate.

Technical Design Scoring Gate

When the user moves from engineering gap review to technical design, read source code and architecture docs before scoring the design.

Fill implementation_mapping.source_code_review:

required=true
status=completed before technical design or delivery plan
paths_read with local code/doc paths
summary with what the code proves
unread_required_paths empty before technical design can pass

Then score implementation_mapping.technical_design_assessment.

Use these dimensions, each 1-5:

architecture_fit: whether the design fits existing Friday architecture and ownership boundaries.
code_reuse: whether existing code/docs/APIs can be reused instead of building a parallel system.
integration_complexity: lower complexity earns higher score; heavy cross-system coupling lowers score.
data_and_memory_fit: whether data, Memory scope, traceability, and write rules are clear.
security_and_compliance: whether permissions, privacy, audit, and compliance review are addressed.
testability: whether the design can be evaluated with fixtures, metrics, and regression.
operability: whether monitoring, fallback, support, and rollback are defined.
delivery_risk: lower delivery uncertainty earns higher score.

Overall ai_score should reflect the weakest major risk, not the average only. A design with one blocking compliance or architecture issue should not score above 3.

Ask the AI engineer to confirm the score. Do not mark engineering_ready unless source_code_review.status=completed, required dimensions are scored, and technical_design_assessment.ai_engineer_confirmation=confirmed.

QA And PoC Gate

Use validation_plan, not scattered acceptance/testing fields.

poc_design_ready requires:

scenario
golden cases or fixture plan
rubric
failure cases
acceptance method
metric definitions

poc_execution_ready additionally requires:

available or approved assets
owners
environment
data permission
privacy approval
regression set
blocking error definition
observability or audit events

Each metric must include:

metric_id
definition
baseline
target
measurement method
fixture id
owner
pass/fail rule

Final Output

When enough information is available, output:

Short human-readable summary.
Completed spec.json following references/spec-schema.json.
Missing fields.
Review recommendation.
Current stage_gate.

For a business handoff, output the human-readable summary, spec.json, missing fields, review recommendation, and current stage_gate. A produced SVG wireframe is required only if the spec is already being marked product_ready or later. If the UI is known but not shaped, set ui_requirements.wireframe_status=needed and list it as the next-stage product blocker.

Use null, empty arrays, or "unknown" for missing facts. Do not invent facts. Important unknowns must appear in missing_fields.

Required top-level sections:

spec_version
spec_id
title
status
priority
stage_gate
opportunity_assessment
product_context
owners
business_context
scope
workflow
friday_object_model
knowledge_and_memory_policy
ui_requirements
capability_boundaries
validation_plan
operation_standards
implementation_mapping
review_gates
missing_fields

If saving JSON to disk, run:

python3 scripts/validate_spec.py <path-to-spec.json>

Final Self-Review

Before returning or saving the final spec, check:

JSON parses.
All required top-level keys are present.
stage_gate.decision matches the real next gate.
needs_more_evidence does not move to engineering delivery.
Evidence refs point to evidence_registry.
PMF scores >= 3 have non-assumption evidence.
competitive_research has a competitor/substitute matrix, differentiation score, and user confirmation when research is required.
product_context.technical_leadership has a claim, proof or argument, agent score, and product owner confirmation before product-ready or later gates.
Domain Pack specs declare the Friday object loop.
Memory write rules have approval, target scope, redaction, and rollback.
UI specs include a produced SVG and reviewed status before product-ready or later gates; business handoff specs may instead record wireframe_status=needed.
validation_plan separates PoC design readiness from execution readiness.
implementation_mapping distinguishes existing, partial, missing, external, and unknown capabilities.
Technical design specs include completed source code review, scoring dimensions, and AI engineer confirmation.
engineering_ready has real owners, no missing fields, and no missing or unknown implementation capabilities.

Style

Use concrete business language.
Prefer multiple-choice questions for non-technical users.
Ask open questions only when the user likely has the detail.
Do not dump a giant JSON template at the start.
Do not hide uncertainty. Make it a blocker or missing field.

stardustai/stardust-skills

What is stardust-skills?

Ask in your favorite AI

Documentation