Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

[Feature]: Add artifact, optional, and handoffs to the command manifest schema

Aberta
  • Algo errado?
#4,209 5 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
4/5
Tempo estimado
3-5 dias
Facilidade para iniciantes
64/100
Tipo de issue
Funcionalidade
Clareza
Razoavelmente clara
Status de atividade
Ativa
Stack de tecnologia
python
Domínio
cli, tooling

Direção de pesquisa

Comece com src/specify_cli/extensions/init.py e src/specify_cli/presets/init.py; em seguida, inspecione relative_extension_path_violation em src/specify_cli/_utils.py e a integração com Forge. Compare o command frontmatter existente em templates/commands/plan.md com os modelos de manifest e determine o normalized handoff mapping. Considera-se concluído quando a validação, a precedência, o comportamento do schema compatível com versões anteriores, o Forge stripping e a documentação estiverem cobertos pela verificação da implementação.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

enhancement feature-assess feature-go
Problem Statement

ExtensionCommand and preset command entries model fields such as type, name, file, description, and strategy, but do not expose artifact (the repo-relative output path a command produces), optional (whether a flow can skip it), or handoffs (declarative follow-on commands).

handoffs currently lives in command frontmatter and is stripped by several markdown integrations, including Forge. This forces downstream consumers such as wizard UIs, flow runners, and pipeline visualizers to re-parse markdown frontmatter and prevents these semantics from being consistently available through the command manifest model.

Proposed Solution

Add optional artifact, optional, and handoffs fields to extension and preset command manifest entries:

commands:
  - name: speckit.plan
    file: commands/speckit.plan.md
    description: "..."
    artifact: specs/{feature}/plan.md
    optional: false
    handoffs:
      - to: speckit.tasks
        when: "plan.status == 'done'"
        message: "Ready to break plan into tasks"

Parse command frontmatter during manifest loading and merge its handoffs into the command entry when the manifest does not declare them. If both sources provide handoffs, the manifest value takes precedence.

Keep handoffs in the in-memory model, while continuing to strip it on the Forge export path. Define how the existing frontmatter shape (label, agent, prompt, send) maps to or coexists with the manifest shape (to, when, message). In other words, add handoffs to the normalized in-memory command model and JSON output. Accept an explicit manifest declaration as an optional override, but derive it from command frontmatter when absent. Authors should not need to duplicate handoffs in both files.

Alternatives Considered
  • Leave handoffs frontmatter-only and require consumers to parse it. Rejected because downstream consumers would duplicate parsing.
  • Derive artifact from the command file. Rejected because a command may produce multiple artifacts or none.
  • Bump schema_version without a compatibility strategy. Current validators use exact-version matching, so a bump would reject existing manifests. Prefer an additive change under the current version unless compatibility policy is deliberately changed.
Component

Specify CLI (initialization, commands)

AI Agent (if applicable)

Not applicable

Use Cases
  1. A wizard renders a Spec-Driven Development pipeline graph by walking handoffs edges without opening markdown files.
  2. A flow runner shows a skip action for commands with optional: true and refuses to auto-skip mandatory commands.
  3. An audit joins a command's artifact path to files in the repository.
Acceptance Criteria
  • Extension and preset command schemas accept optional artifact (string), optional (bool, default false), and handoffs (list of {to, when?, message?}).
  • The manifest loader merges command-file frontmatter handoffs when the manifest does not declare its own value.
  • Manifest-declared handoffs takes precedence over frontmatter.
  • Forge export continues to strip handoffs from exported frontmatter.
  • artifact is validated as repo-relative; handoffs[].to resolves to a known command; optional is validated as a boolean.
  • The schema-version decision is recorded, with backward-compatible behavior for existing manifests.
  • Valid and malformed manifest entries, frontmatter merge precedence, and Forge stripping are covered by the implementation verification.
  • The manifest schema and handoffs semantics are documented in the relevant existing documentation.
Additional Context

Impacts preset info --json / extension info --json, which are tracked separately.

Relevant implementation locations include src/specify_cli/extensions/__init__.py, src/specify_cli/presets/__init__.py, src/specify_cli/_utils.py::relative_extension_path_violation, and src/specify_cli/integrations/forge/__init__.py. Existing command frontmatter examples include templates/commands/plan.md.

Linguagem predominante
Python
Estrelas
140k
Forks
12.6k
Merge médio
2d 13h
PRs com merge (30d)
197

Preparar o ambiente

Abrir no Codespaces

Inicia o contêiner de desenvolvimento do projeto no navegador, com a sua própria conta do GitHub.

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de github/spec-kit

Todas as issues de github/spec-kit

Issues semelhantes

Mais issues de Python

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.