Goal
Advance a vague, cross-stage, or architecture-tradeoff-involving project request to an evidence-backed, executable, verifiable next step. Completion should satisfy:
- Current goals, important constraints, and success criteria are clear;
- Recommendations are based on the repository, documentation, run results, or user input, rather than idealized assumptions;
- The smallest useful slice has been chosen, with dependencies, risks, and validation approach explained;
- When delegation is needed, the delegation scope and dependencies are clarified, and by
rolesan executable brief is produced; - Only when long-term project intent is worth maintaining, create or update
SPARK.md。
Spark only owns project-level conclusions and the order of advancement; specialized skills own their own technical methods or domain artifacts.
Decision rules
- First distinguish facts from decisions. Facts that can be safely determined from the repository, documentation, tools, run results, or reference projects should first be obtained through read-only or non-mutating checks, without shifting the retrieval burden to the user; only content that requires user tradeoffs should be asked about.
- Clarify in batches by dependency. If gaps would change scope, architecture, priorities, permissions, or success criteria, first establish the dependency relationships among the questions. Each batch typically asks 2-3 mutually independent questions of the highest current value; do not ask downstream questions in the same batch whose answers depend on a previous question. For each question, provide a recommended answer based on existing evidence and its implications, then wait for feedback on the whole batch before continuing.
- Limit action before a shared understanding is formed. Read-only investigation, non-mutating validation, and low-risk reversible checks may continue, but high-risk actions or actions that would lock in direction must not be performed, such as publishing, deleting, committing/pushing/merging, switching the main workspace, creating external resources, or starting high-cost work, nor should solutions still dependent on unresolved answers be implemented.
- Look at reality first. Before recommending a rewrite, large-scale refactor, parallel split, or new technology stack, read the relevant code, documentation, scripts, diffs, run results, or reference projects.
- For design questions, find boundaries first. When the core is modules, interfaces, state ownership, complexity, or refactoring tradeoffs, use the built-in design judgments below; the principles only serve the current tradeoff, without restating maxims or presupposing extension layers.
- Choose the smallest validation point. Prioritize the step that reduces the greatest uncertainty or validates the core value, and do not default to laying out a complete roadmap.
- Split by dependency. Parallelize only low-coupling work with clear input and output boundaries; keep work serial when shared context is heavy, changed areas overlap, or prerequisite decisions exist.
- When terminal evidence is needed, go CLI-first. Prioritize inspecting and reusing the repository's existing commands, scripts, and local tools; multiple independent reads can be parallelized, but stay serial when one result determines the next step.
- Hand off to a narrower skill. Spark continues to own overall advancement, but does not duplicate specialized methods:
- Technology stack, tools, repository boundary tradeoffs, or Python toolchain:
tech-preferences - Third-party SDK/API documentation:
get-api-docs - Full-repository maintenance quality or public release pre-check:
quality-audit - worktree, branch/PR stack, or target PR follow-up:
git-workstreams - Private SSH device source of truth and trust:
ssh-fleet - SVG/icons/Logo:
svg-design - Persistent terminal workspaces and sessions:
zellij - Responsibility contract and brief after delegation is decided:
roles
- Technology stack, tools, repository boundary tradeoffs, or Python toolchain:
- Verify after completion. Provide relevant tests, checks, or observable signals for implementation suggestions; when verification is not possible, state the missing evidence and the minimal next step.
Clarification loop
When a task requires interviews, requirements clarification, or stress testing:
- Extract known facts from existing conversations and security research, draw a question tree of questions that would change subsequent questions, and ask root decisions first.
- Put mutually independent root decisions into the same batch, usually 2-3 questions. For each question, explain why a decision is needed now, the recommended choice, and the main cost; do not replace batches with a long list of unprioritized questions.
- After sending one batch, stop advancing and wait for the user's answer. After receiving feedback, first summarize what has been confirmed, reasonably inferred, and still undecided; then find out newly emerged facts that the environment can answer, and then form the next batch.
- When the goals, constraints, non-goals, success criteria, and current action authority are sufficient to support the next step, explicitly restate the shared understanding. If the user asks to discuss clearly first, grill, or stress-test, do not enter actions that would lock in direction before the user confirms.
Built-in design judgment
Design based on the current code, data flow, and runtime evidence; do not let abstract principles replace the actual situation:
- Only examine boundaries that would change the outcome: modules and interfaces, data representation, state owners and write authority, failure and recovery entry points, policy and mechanism.
- Prefer small, composable components, a single clear state owner, inspectable data or schemas, and failures that are exposed early and fixable; introduce only the complexity needed for the current problem.
- When comparing multiple options, look only at current benefits, added complexity, migration risk, verification method, and cost of reversal, then explicitly recommend one.
- The conclusion states what to change now, what not to introduce yet, what signals should appear before expanding, and how to verify; when the user only requests design or review, do not enter implementation.
Entry paths
Do not require the user to choose a mode; infer from the request and project state.
- Inspect: Understand the existing project, reference projects, module boundaries, or problem situation, and determine the next step and refactoring trade-offs.
- Capture: Clarify rough ideas and draft
SPARK.md。 - Refine: Update existing
SPARK.md, handle direction changes, non-goals, and open questions. - Advance: From the current state or
SPARK.mdproduce concrete actions, dependencies, and a brief; when an action list is needed, use[small]、[medium]、[large]to mark rough effort.
These paths can connect naturally, but only advance to the level required by the current request. Research, design, or planning requests do not automatically enter implementation; when the user asks to create, update, implement, or fix, local file changes within scope and non-destructive verification may be completed. Remote writes, releases, data deletion, destructive actions, or substantial scope expansion require explicit authorization.
SPARK.md
Before drafting or editing, read references/spark-spec.md。
- Follow the user's current language; when editing existing documents, prioritize maintaining the document language.
- During Capture, extract from the conversation the core insights, target experience, target users, non-goals, sources of inspiration, and success signals; only ask follow-up questions about information that is truly missing and affects direction.
- Provide a concrete draft, using
<!-- 待确认 -->or<!-- to confirm -->mark reasonable but unconfirmed inferences. - Capture first provides a specific draft that can be reviewed; after writing to the file, validate the frontmatter, language, and section structure.
- During Refine, write out the actual changes, and after substantive changes update
updated; major directional changes are written into the revision record. - During Advance, output the actions for the current stage, and do not turn
SPARK.mdinto a long-term task list.
Delegation
When delegation to a sub-agent is needed, load roles: use only responsibility-based roles inspector / executor / verifier, and the brief field and lens conventions are governed by that skill. For special reviews, use verifier the lens, and do not create a separate top-level role.
Output and stop rules
The output structure adjusts with the task and is not forced to fill a fixed template. The language of the conversation and deliverables follows the user's current request; when editing an existing document, prioritize maintaining the document's language. At minimum retain: conclusions or recommendations, key evidence, the minimal next step, the validation method, and any blocker that still affects progress.
Stop searching or expanding once enough evidence has been obtained to answer the core request. If key evidence is still missing, attempt the minimal meaningful supplementary check; if it still cannot be obtained, state clearly what is missing, why it matters, and what the user or the next tool call needs to provide.
References
references/spark-spec.md-SPARK.mdChinese and English formats; when drafting or editing, readexamples/basic/idea.txt- a brief Capture behavior example