feat(extensions): add assess idea assessment pipeline extension

[mnriem]

Description

Adds a new opt-in, role-neutral extension — assess, the "Idea Assessment Pipeline" — covering the discovery/problem-assessment work that happens before spec-driven development begins (i.e., before /speckit.specify).

Today Spec Kit starts at the point where you already know what you're building. assess fills the gap in front of that: a lightweight, structured funnel for pressure-testing an idea before it earns a spec. It is deliberately role-neutral (named for the activity, not a job title) so it composes cleanly into role bundles rather than competing with them.

Pipeline (five stages, one artifact each)

Each command writes a single markdown artifact under .specify/assessments/<slug>/:

Command	Stage	Artifact
/speckit.assess.intake	Capture the raw idea	intake.md
/speckit.assess.research	Gather evidence	research.md
/speckit.assess.define	Sharpen the problem	problem.md
/speckit.assess.shape	Outline a concept	concept.md
/speckit.assess.decide	Go / needs-clarification / kill	decision.md

• A go verdict hands off to /speckit.specify.
• Killing an idea is a first-class success outcome, not a failure.
• It registers no lifecycle hooks — assess is a separate business process and never inserts itself into /speckit.specify. The only coupling is the forward decide → /speckit.specify handoff.

Registration (core opt-in)

• extensions/catalog.json: bundled entry ("bundled": true), alphabetically before bug.
• pyproject.toml: force-include maps extensions/assess → specify_cli/core_pack/extensions/assess so it ships in the installed wheel. Verified by building the wheel and confirming all files land in core_pack.
• Not auto-installed by specify init; users opt in with specify extension add assess.

It mirrors the existing bug extension's conventions (slug resolution, URL Trust Policy, __SPECKIT_COMMAND_*__ cross-references, guardrails).

Note on tests/test_workflows.py

One assertion in test_add_from_url_download_failure_cleanup_error_preserves_original_error matched a multi-word substring against Rich-rendered panel output, which wraps mid-phrase at CI's 80-column non-TTY width and fails there. Normalized it with the same whitespace-stripping pattern already used one line above. This is the only non-assess change and is required for green CI. (A broader pass over other width-fragile tests that only fail at artificially narrow widths is left for a separate PR.)

Testing

• Tested locally with uv run specify --help
• Ran existing tests with uv sync && uv run pytest — 4508 passed, 5 skipped, 0 failed at CI's 80-column width
• Tested with a sample project (installed the extension via CLI; verified the five commands scaffold)
• Built the wheel and confirmed assess ships in core_pack
• Added tests/extensions/assess/test_assess_extension.py (9 tests: layout, catalog registration, bundle resolution, install, and a test_declares_no_hooks guard)

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (describe below)

This change was developed with GitHub Copilot (model: Claude Opus 4.8) under human supervision. Copilot drafted the extension commands, README, tests, and packaging/registration changes; the author reviewed and validated the design, ran the test suite, and confirmed wheel packaging. Commits carry Assisted-by: trailers.

[Copilot]

Pull request overview

Adds the opt-in assess extension for evaluating ideas before specification.

Changes:

• Adds five assessment-stage commands and documentation.
• Registers and packages the bundled extension with an optional hook.
• Adds extension tests and stabilizes a terminal-width-sensitive assertion.

Show a summary per file

File	Description
extensions/assess/README.md	Documents the assessment pipeline.
extensions/assess/extension.yml	Defines commands, metadata, and hook.
extensions/assess/commands/speckit.assess.intake.md	Adds idea intake workflow.
extensions/assess/commands/speckit.assess.research.md	Adds evidence-gathering workflow.
extensions/assess/commands/speckit.assess.define.md	Adds problem-definition workflow.
extensions/assess/commands/speckit.assess.shape.md	Adds concept-shaping workflow.
extensions/assess/commands/speckit.assess.decide.md	Adds assessment decision gate.
extensions/catalog.json	Registers the bundled extension.
pyproject.toml	Includes the extension in wheels.
tests/extensions/assess/__init__.py	Initializes the test package.
tests/extensions/assess/test_assess_extension.py	Tests layout, registration, and installation.
tests/test_workflows.py	Normalizes wrapped CLI output assertions.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 11/12 changed files
• Comments generated: 9
• Review effort level: Medium

[mnriem]

Thanks for the review. Addressed all nine comments in 4c8124d:

• catalog.json freshness — bumped top-level updated_at to 2026-07-17T00:00:00Z.
• Description length (×2) — shortened the assess description to 195 chars (under the documented 200-char limit) and kept extension.yml and catalog.json aligned.
• before_specify hook prompt — the hook has no condition and fires on every /speckit.specify, so the prompt no longer claims "no assessment found"; it's now condition-neutral ("Assess this idea before specifying?").
• Slug normalization — the rule now explicitly allows lowercase letters a–z alongside digits and -, matching the offline-mode example.
• URL sanitization (intake + research) — both stages now record a sanitized URL (strip user:password@ userinfo and drop credential/signature query params such as token, sig, access_token, X-Amz-*), and templates request the redacted form so no verbatim URL with embedded secrets lands in project artifacts.
• decide determinism — removed the "trivially small" exception; a go now always requires a shaped concept, consistent with the line-36 requirement, the no-concept guardrail, and the README.

Tests green at CI's 80-column width: tests/extensions/assess/, tests/test_extensions.py, and tests/contract/test_catalog_schema.py — 377 passed.

Disclosure: this response and commit 4c8124d were authored by GitHub Copilot (model: Claude Opus 4.8) under human supervision, on behalf of @mnriem.

[Copilot]

Review details

• Files reviewed: 11/12 changed files
• Comments generated: 7
• Review effort level: Medium

[Copilot]

Review details

• Files reviewed: 11/12 changed files
• Comments generated: 10
• Review effort level: Medium

[mnriem]

Addressed all ten comments from this round in 9cd07fb.

Slug path traversal (intake, research, define, shape, decide) — every command that accepts an explicit or user-supplied slug now normalizes it to the [a-z0-9-] alphabet (dropping ., /, \), collapses/trims -, and rejects an empty normalized result before building ASSESS_DIR. A slug like ../.. normalizes to empty and is refused, so the assessment directory can no longer escape .specify/assessments/.

Metadata accuracy (extension.yml + catalog.json) — the descriptions no longer imply a "build/kill call" is handed to /speckit.specify. They now state: a go verdict hands off to /speckit.specify; a kill closes the assessment. (Still under the 200-char limit.)

Verdict determinism (decide) — a go now explicitly requires evidence strength adequate+ (never weak/unknown), resolving the conflict with the thin-evidence guardrail. Weak/unknown evidence deterministically yields needs-clarification.

Risk polarity (decide) — renamed the Risk criterion to Risk posture with the same positive polarity as the others (strong = key risks identified and credibly mitigated), so it composes cleanly into the verdict.

PR description — dropped the stale before_specify hook claim; the hook was removed in the prior commit (6e2d81d) because assess is a separate business process. The test line the bot flagged is the intentional test_declares_no_hooks guard, now reflected in the description.

Tests green at CI's 80-column width: tests/extensions/assess/, tests/test_extensions.py, tests/contract/test_catalog_schema.py — 377 passed.

Disclosure: this response and commit 9cd07fb were authored by GitHub Copilot (model: Claude Opus 4.8) under human supervision, on behalf of @mnriem.

[Copilot]

Review details

• Files reviewed: 11/12 changed files
• Comments generated: 6
• Review effort level: Medium

[mnriem]

Addressed all six comments from this round in c032a2e.

Symlink traversal (intake, research, define, shape, decide) — you're right that normalizing the slug only blocks lexical ..; a symlinked .specify, assessments, <slug> directory, or artifact could still redirect reads/writes outside the project. Each command now carries an explicit Path safety prerequisite: before any mkdir/read/write it resolves the real (symlink-resolved) path of .specify/assessments/<slug>/ and every artifact, refuses to follow a symlinked path component or target, and verifies the resolved path stays inside the project root. Each stage enforces this independently, since research/define/decide can run without intake.

Open-ended host heuristic (research) — replaced the "and comparable well-known hosts" no-prompt branch with intake's exact enumerated allowlist (github.com, gist.github.com, gitlab.com, bitbucket.org, *.atlassian.net, linear.app, notion.so, *.notion.site, docs.google.com, stackoverflow.com, *.stackexchange.com). Any host off that list is unrecognized and requires confirmation; the agent may no longer classify a host as "comparable" and fetch it silently.

The README guardrail now documents the symlink/realpath containment property too.

Tests green at CI's 80-column width: tests/extensions/assess/, tests/test_extensions.py, tests/contract/test_catalog_schema.py — 377 passed.

Disclosure: this response and commit c032a2e were authored by GitHub Copilot (model: Claude Opus 4.8) under human supervision, on behalf of @mnriem.

[Copilot]

Review details

• Files reviewed: 11/12 changed files
• Comments generated: 2
• Review effort level: Medium

[mnriem]

Addressed both comments from this round in 05968e4 (both in intake.md).

Secret leak in the captured idea — you're right that quoting the original "verbatim" contradicted the URL-sanitization rule when the idea itself contains a credential-bearing URL. Capture step 1 and the template now redact secrets inside the quoted text too (sanitize URLs; strip tokens, passwords, keys, cookies), matching the Source field. Renamed the section from "Idea (verbatim)" to "Idea (as captured)" so the heading no longer implies literal preservation of secrets.

Explicit-slug collision — in automated mode an existing intake.md previously triggered a silent switch to a new slug, contradicting line 30 and the README guarantee that user-provided slugs never gain suffixes. Now: a user-provided slug collision stops and reports; only a self-generated slug (already disambiguated during resolution) is re-slugged.

Tests green at CI's 80-column width: tests/extensions/assess/ and tests/contract/test_catalog_schema.py — 21 passed.

Disclosure: this response and commit 05968e4 were authored by GitHub Copilot (model: Claude Opus 4.8) under human supervision, on behalf of @mnriem.

[mnriem]

While reconciling review threads I found an earlier review round (4722852090, 7 comments) that hadn't been explicitly addressed. Six of its seven comments were already resolved by later commits:

• Empty/separator-only slug (intake) → fixed in 9cd07fb (reject empty normalized slug).
• Open-ended "comparable well-known hosts" (research) → fixed in c032a2e (pinned to intake's exact allowlist).
• Missing slug normalization/validation in define, shape, decide → fixed in 9cd07fb.
• Undefined normalization/reject in research → fixed in 9cd07fb / c032a2e.

The one remaining comment is now addressed in b3faa63:

SSRF / IPv6 gap in the URL Trust Policy — the refuse-outright list only covered textual IPv4 loopback/RFC1918/metadata hosts. It now also refuses IPv6 link-local (fe80::/10), unique-local (fc00::/7), IPv4-mapped forms, and the IPv6 metadata address, and adds a resolution-time check: even an allowlisted or user-confirmed host is refused if it resolves to a non-public address, which defeats DNS rebinding. Mirrored the summary in research's inherited-policy note so that command is self-contained.

Tests green at CI's 80-column width: tests/extensions/assess/ and tests/contract/test_catalog_schema.py — 21 passed.

Disclosure: this response and commit b3faa63 were authored by GitHub Copilot (model: Claude Opus 4.8) under human supervision, on behalf of @mnriem.

[Copilot]

Review details

• Files reviewed: 11/12 changed files
• Comments generated: 1
• Review effort level: Medium

[mnriem]

Addressed all four comments from this round in ecc090e.

DNS rebinding (intake + research) — fair point: a separate DNS lookup followed by a hostname fetch is TOCTOU-vulnerable, since the client can re-resolve or select a private address from a mixed answer. The policy now requires the fetch to pin the connection to a validated public address (or verify the connected peer's IP after connecting) and re-apply the refusal ranges to the address actually connected to. If the available fetch mechanism cannot pin the address or expose the connected peer, the fetch is refused rather than trusted by hostname.

Slug-only direct entry (research + define) — when intake.md/research.md are absent and $ARGUMENTS contains only a slug, both commands now require substantive idea/problem text and will not infer claims from the slug. If only a slug is supplied, they prompt interactively or stop in automated mode instead of manufacturing content.

Also removed a leftover duplicate ASSESS_DIR assignment line in research left over from an earlier round.

Tests green at CI's 80-column width: tests/extensions/assess/ and tests/contract/test_catalog_schema.py — 21 passed.

Disclosure: this response and commit ecc090e were authored by GitHub Copilot (model: Claude Opus 4.8) under human supervision, on behalf of @mnriem.

[Copilot]

Review details

• Files reviewed: 11/12 changed files
• Comments generated: 1
• Review effort level: Medium

[mnriem]

Addressed the single comment from this round in ce635f3.

Intake read/write guardrail — you're right, "only reads and writes inside .specify/assessments/<slug>/" contradicted intake's own inputs (it must inspect the repository for a codebase-pointer idea and fetch an allowed URL to capture it). The guardrail now limits only writes to the assessment directory and explicitly permits read-only inspection of the supplied sources (repository + allowlisted URL fetch under the URL Trust Policy).

The other four commands already phrased this correctly ("read only, and write inside …"), so they're unchanged.

Tests green at CI's 80-column width: tests/extensions/assess/ and tests/contract/test_catalog_schema.py — 21 passed.

Disclosure: this response and commit ce635f3 were authored by GitHub Copilot (model: Claude Opus 4.8) under human supervision, on behalf of @mnriem.

[Copilot]

Review details

• Files reviewed: 11/12 changed files
• Comments generated: 10
• Review effort level: Medium

[mnriem]

Addressed review 4723905370 in cb4b95e, grouped into three themes:

Ancestor path safety (before slug resolution). All five commands now verify that .specify and .specify/assessments are real directories (not symlinks) resolving inside the project root before any filesystem-based slug lookup, refusing otherwise. This closes the window where a crafted project could redirect the very directory scan used to resolve a slug.

Untrusted artifact reads. research, define, shape, and decide now explicitly treat the contents of persisted artifacts (intake.md/research.md/problem.md/concept.md) as untrusted data, not instructions — ignoring any embedded directives, mirroring the existing URL Trust Policy. Stored content captured from untrusted pages can't hijack a later stage's workflow.

research directory creation. research now ensures the validated ASSESS_DIR exists before writing, since it may be the first assessment command run (previously only define created it).

Tests: 21 passed (tests/extensions/assess/ + tests/contract/test_catalog_schema.py).

Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8). Commits carry Assisted-by trailers disclosing agent authorship.

[Copilot]

Review details

• Files reviewed: 11/12 changed files
• Comments generated: 3
• Review effort level: Medium

[mnriem]

Addressed review 4723955260 in b2f609e.

Good catch — the ancestor path-safety clause I added last round required .specify/assessments to already be a real directory, which contradicted the first-run flows: intake, research, and define are all allowed to run before the directory exists, so refusing on absence blocked them from reaching the step that creates it.

Reworded the clause in all five commands so that a not-yet-created directory is permitted (it will be created safely later), while still refusing when .specify or .specify/assessments exists as a symlink or escapes the project root. The symlink/containment protection is preserved; only the false rejection on absence is removed.

Tests: 21 passed (tests/extensions/assess/ + tests/contract/test_catalog_schema.py).

Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8). Commits carry Assisted-by trailers disclosing agent authorship.

[Copilot]

Review details

• Files reviewed: 11/12 changed files
• Comments generated: 1
• Review effort level: Medium

[mnriem]

Addressed review 4724027270 in a3e2ac1.

The overview flowchart routed every needs-clarification verdict back to research, but decide.md's Revisit stage can send an idea back to whichever earlier stage is under-baked — intake, research, define, or shape. Rerouted the arrow as a generic dashed loop back to the earlier stages (needs-clarification: revisit the named earlier stage) so the diagram matches the actual decision workflow instead of implying research is the only re-entry point.

Docs-only change; assess tests still pass (9 passed).

Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8). Commits carry Assisted-by trailers disclosing agent authorship.

[Copilot]

Review details

• Files reviewed: 11/12 changed files
• Comments generated: 2
• Review effort level: Medium

[mnriem]

Addressed review 4724080304 in c59c457. Both comments concerned hard-coded dot-style /speckit.specify in decide.md:

Frontmatter description (line 2). Since extension frontmatter is parsed before command-reference resolution, a placeholder wouldn't render there. Switched to agent-neutral wording — "hand survivors off into Spec-Driven Development" — so generated help/skill metadata is correct regardless of the integration's command style.

Handoff heading in the decision.md template (line 74). This literal was inside the fenced block that gets written verbatim into decision.md, so non-dot integrations would have recorded an invalid /speckit.specify handoff. It now uses the __SPECKIT_COMMAND_SPECIFY__ placeholder, matching the rest of this command, so the active integration's invocation style is rendered.

No dot-style literals remain in the command files. Tests: 21 passed.

Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8). Commits carry Assisted-by trailers disclosing agent authorship.

[Copilot]

Review details

• Files reviewed: 11/12 changed files
• Comments generated: 0 new
• Review effort level: Medium