Create consolidated SPEC.md for feature-triage compatibility #224

New issue

Closed

opened 2026-05-14 14:28:03 +00:00 by Mark · 2 comments

Mark commented

2026-05-14 14:28:03 +00:00

Owner

Problem

The feature-triage cron cannot properly assess feature requests filed against mesh-seed because there is no single consolidated spec file (SPEC.md or equivalent). The project has documentation spread across AGENTS.md, ARCHITECTURE.md, PHILOSOPHY.md, MILESTONES.md, and various docs/ files, but the triage engine only reads from known spec paths.

This caused 5 feature requests (#219-223) to be deferred with weak assessments ("needs investigation") and eventually closed as misaligned.

Expected

Create a SPEC.md or similar file in the project root that:

Describes what mesh-seed IS and IS NOT (critical for catching wrong-repo filings)
Documents current architecture, capabilities, and roadmap
Lists what subsystems exist and what decisions have been made
Follows the convention expected by the triage pipeline so future feature requests get proper scope/risk/spec-alignment assessments

Format can be terse — doesn't need to duplicate existing docs, just consolidate the key architectural boundaries and project identity so an automated triage LLM can assess feature requests against it.

Existing Documentation (do not rewrite these, reference them)

AGENTS.md — coding guidelines + architecture principles
ARCHITECTURE.md — system architecture
PHILOSOPHY.md — design philosophy
MILESTONES.md — milestone tracking
docs/ — detailed technical documentation

Acceptance Criteria

SPEC.md exists at project root
Contains clear project identity scope (what mesh-seed is for)
References existing docs rather than duplicating them
Feature-triage cron can assess new feature requests against it

## Problem The feature-triage cron cannot properly assess feature requests filed against mesh-seed because there is no single consolidated spec file (SPEC.md or equivalent). The project has documentation spread across AGENTS.md, ARCHITECTURE.md, PHILOSOPHY.md, MILESTONES.md, and various docs/ files, but the triage engine only reads from known spec paths. This caused 5 feature requests (#219-223) to be deferred with weak assessments ("needs investigation") and eventually closed as misaligned. ## Expected Create a SPEC.md or similar file in the project root that: - Describes what mesh-seed IS and IS NOT (critical for catching wrong-repo filings) - Documents current architecture, capabilities, and roadmap - Lists what subsystems exist and what decisions have been made - Follows the convention expected by the triage pipeline so future feature requests get proper scope/risk/spec-alignment assessments Format can be terse — doesn't need to duplicate existing docs, just consolidate the key architectural boundaries and project identity so an automated triage LLM can assess feature requests against it. ## Existing Documentation (do not rewrite these, reference them) - AGENTS.md — coding guidelines + architecture principles - ARCHITECTURE.md — system architecture - PHILOSOPHY.md — design philosophy - MILESTONES.md — milestone tracking - docs/ — detailed technical documentation ## Acceptance Criteria - [ ] SPEC.md exists at project root - [ ] Contains clear project identity scope (what mesh-seed is for) - [ ] References existing docs rather than duplicating them - [ ] Feature-triage cron can assess new feature requests against it