🧠 Introduce spec-driven development workflow

[Copilot]

The repository lacked a structured way to define feature behavior before implementation, leaving AI agents and developers to interpret intent from issues and PRs. This introduces a spec-driven layer that acts as the authoritative behavior contract for each feature.

New: specs/ directory

• specs/README.md — workflow documentation: why specs exist, the 5-step lifecycle (write → issue → implement → review → close loop), status states (draft / approved / implemented / superseded), file naming rules, and how specs relate to ARCHITECTURE.md, issues, and ai/factory/workflow/
• specs/_template.md — canonical template with YAML frontmatter (feature, status, issue, pr, created, updated) and sections for Objective, Behavior (checkbox criteria + Given/When/Then scenarios), Non-Goals, Architecture Notes, and References

ARCHITECTURE.md

• specs/ added to the Repository Layout tree
• New Spec-Driven Development section (ToC item 21): purpose, lifecycle table, workflow diagram, agent rules, spec format summary
• Adding a New Feature checklist updated: writing a spec is now step 1; updating spec status to implemented is the final step

README.md

• New Spec-Driven Development section summarising the 5-step flow with links to specs/README.md and ARCHITECTURE.md#spec-driven-development

.github/copilot-instructions.md

• New When implementing a feature block: agents must locate and read specs/<feature-name>.md before writing code, treat each acceptance criterion as a hard requirement, not deviate without updating the spec first, and confirm all criteria are met at the end

Original prompt

---

This section details on the original issue you should resolve

<issue_title>🧠 Introduce spec-driven development workflow into flutter-foundation</issue_title>
<issue_description>Objective

Introduce a spec-driven development workflow into the flutter-foundation repository.

Context

The repository currently uses architecture-driven development combined with AI agents and issue-based workflows. To improve clarity, consistency, and AI reliability, a spec-driven layer should be introduced.

Specs will act as structured contracts that define feature behavior before implementation.

Scope

• Define how specs integrate into the existing workflow
• Establish specs as a source of truth for feature behavior
• Define how specs relate to ARCHITECTURE.md, issues, and agents
• Ensure compatibility with the AI workflow system in ai/factory/

Acceptance Criteria

• Spec-driven workflow is defined and documented
• Relationship between specs, issues, and agents is clear
• Workflow integrates with existing architecture and issue system
• Documentation updated to reflect the new workflow</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes 🧠 Introduce spec-driven development workflow into flutter-foundation #73

---

📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.

[Copilot]

@szmyty Unfortunately, I hit an error while trying to use the custom Copilot setup steps configured for this repository and had to close this PR. The error I am seeing is:

no `copilot-setup-steps` job found in your `copilot-setup-steps.yml` workflow file. Please ensure you have a single job named `copilot-setup-steps`. For more details, see https://gh.io/copilot/actions-setup-steps

Once you or someone with the necessary access fixes the problem, please unassign and then reassign issue #0 to me and I'll retry. Thanks!

[devactivity-app]

Pull Request Summary by devActivity

Metrics

Achievements

• @szmyty
  Earned XP: 15⭐
  Check Your Progress