Skip to content

Adopt spec-kit + Claude workflow: constitution v1.0.0 + AGENTS.md#91

Open
yarikoptic wants to merge 2 commits into
masterfrom
enh-ai
Open

Adopt spec-kit + Claude workflow: constitution v1.0.0 + AGENTS.md#91
yarikoptic wants to merge 2 commits into
masterfrom
enh-ai

Conversation

@yarikoptic
Copy link
Copy Markdown
Member

Summary

Bootstrap the spec-kit + Claude workflow for this repository. This PR
is a governance + tooling change, not a behaviour change — no Python code
in tributors/ is touched.

  • .specify/ scaffolding (commit ed9d07a, [DATALAD RUNCMD]):
    introduces .specify/{templates,scripts,workflows,integrations, extensions,memory}/, the .specify/extensions.yml hook config, and
    the per-command skills under .claude/skills/speckit-*/ that back the
    /speckit.* slash-commands.
  • Constitution v1.0.0 (.specify/memory/constitution.md, commit
    cae8c99): five principles ratified, centred on what Tributors is
    for — adequate contributor acknowledgement and automation of the
    bookkeeping that has historically been manual.
  • AGENTS.md at the repo root (new, commit cae8c99): canonical
    entry point for AI agents (Claude Code, Codex, Cursor, Aider, …) and
    for humans wanting a quick orientation. Preserves the prior CLAUDE.md
    build/test/style content and points to the constitution as required
    reading.

Why this is the starting point

Going forward, non-trivial work on this repo flows through spec-kit's
phased commands:

/speckit.specify  →  /speckit.clarify  →  /speckit.plan  →  /speckit.tasks  →  /speckit.implement

Each phase produces a reviewable artifact under specs/<###-feature>/
(spec → plan → research/data-model/contracts/quickstart → tasks). The
constitution is the gate every plan is checked against, so it is
ratified first. AGENTS.md is the shared entry point that AI agents
load before proposing changes, so it is created at the same time.

What is intentionally not in this PR

  • No changes to parsers, the CLI, the container, or the GitHub Action.
  • No new dev dependencies. The constitution's "Style" Quality Gate
    notes that black/pyflakes are operator-installed today and not
    wired into CI; promoting them to a CI-enforced MUST is the one
    recorded deferred TODO and will land in a follow-up PR.
  • No spec/plan for a feature — those come in subsequent PRs invoking
    /speckit.specify etc.
Constitution principles (ratified at v1.0.0)
  1. Comprehensive Contributor Acknowledgement — inclusive by default;
    bots excluded because not people.
  2. Named Contributor Fields Are Sacred (NON-NEGOTIABLE) — once
    truthy, name / email / affiliation / orcid / blog / bio
    in any managed contributor file MUST NOT be overwritten by an
    automated run. (Scoped to named fields to match what the codebase
    actually enforces; container-structure ordering is a SHOULD.)
  3. Pluggable Parsers & Shared Cache — every format is a
    ParserBase subclass; cross-parser state flows through .tributors
    indexed by GitHub login.
  4. Automation Across Equivalent Surfaces — library, CLI, container,
    and GitHub Action stay in lockstep with matching options.
  5. Identity Resolution with Human-in-the-Loop — ambiguous matches
    prompt (or skip); never silently guess.

Plus normative sections on Metadata & Standards Compliance and
Development Workflow & Quality Gates, and a Governance section
designating AGENTS.md as the constitution's delegate for day-to-day
conventions.

Files touched
  • .specify/memory/constitution.md (template placeholders → ratified
    v1.0.0)
  • AGENTS.md (new; canonical AI-agent guidance)
  • (plus the prior .specify/ scaffolding in ed9d07a)

CLAUDE.md is locally excluded (.git/info/exclude) and symlinked to
AGENTS.md on the contributor's checkout; it is not tracked.

Test plan

  • Render .specify/memory/constitution.md on GitHub; verify Sync
    Impact Report (HTML comment) is hidden in the rendered view and
    principle headings are at the right level.
  • Render AGENTS.md on GitHub; verify the spec-kit command table
    is column-aligned in source and renders cleanly.
  • Invoke /speckit.specify "<some toy feature>" in a follow-up
    branch to confirm the spec-kit + constitution loop works
    end-to-end against this baseline.

yarikoptic and others added 2 commits May 16, 2026 09:30
=== Do not change lines below ===
{
 "chain": [],
 "cmd": "specify init .",
 "exit": 0,
 "extra_inputs": [],
 "inputs": [],
 "outputs": [],
 "pwd": "."
}
^^^ Do not change lines above ^^^
Populate .specify/memory/constitution.md (previously template placeholders
only) with five principles centred on the project's actual ideals:
comprehensive contributor acknowledgement, named-contributor fields are
sacred, pluggable parsers + shared .tributors cache, automation across
equivalent surfaces (library/CLI/container/Action), and identity
resolution with human-in-the-loop.

Add AGENTS.md at the repository root as the canonical guidance file for
AI agents (Claude Code, Codex, Cursor, Aider, …) and humans wanting a
quick orientation — preserves the prior build/test/code-style content,
adds a spec-kit command cheat-sheet, and points to the constitution as
required reading. CLAUDE.md (locally excluded) is symlinked to AGENTS.md.

Principle II is intentionally scoped to the *named* contributor fields
(`name`, `email`, `affiliation`, `orcid`, `blog`/`profile`, `bio`) — the
exact set the codebase currently protects in its merge logic. List
ordering across runs is a SHOULD, not a MUST.

The Quality Gates "Style" item notes that `black`/`pyflakes` are
operator-installed today; promoting the gate to a MUST in CI is the only
listed deferred TODO.

Co-Authored-By: Claude Code 2.1.143 / Claude Opus 4.7 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant