8000 Contributor workflow: AGENTS.md, DEVELOPMENT.md, .specs/ and start-issue skill by simon-inkie · Pull Request #40 · simon-inkie/inkie-deck · GitHub
[go: up one dir, main page]

Skip to content

Contributor workflow: AGENTS.md, DEVELOPMENT.md, .specs/ and start-issue skill - #40

Merged
simon-inkie merged 2 commits into
mainfrom
39-contributor-workflow
Oct 4, 2026
Merged

simon-inkie merged 2 commits into
mainfrom
39-contributor-workflow

Conversation

@simon-inkie
Copy link
Copy Markdown
Owner

Closes #39

Changes

  • AGENTS.md: single shared rules file. Git workflow moved here from CLAUDE.md.
  • CLAUDE.md: now @AGENTS.md plus a note on the skill symlink, so the two cannot drift.
  • DEVELOPMENT.md: issue first, <issue>-<slug> branch, SPEC in the first commit and updated with the code, early draft PR, resuming from a SPEC.
  • .agents/skills/start-issue/SKILL.md: canonical skill.
  • .claude/skills/start-issue: relative symlink to the canonical copy. One copy only.
  • .specs/39-contributor-workflow/SPEC.md: this change's own SPEC, in the first commit.

No code changes.

Checks

  • node scripts/leak-gate.mjs on the new files: clean. --self-test: passes.
  • No em-dashes in the new docs.
  • Symlink resolves: .claude/skills/start-issue/SKILL.md reads the canonical file.

Dry run: "start issue 22"

Following the skill by hand in a throwaway worktree (discarded, not committed). It has not been run by a separate fresh agent.

Branch: 22-install-clone-step. First commit Start #22: INSTALL.md never tells you to clone the repo touched only .specs/22-install-clone-step/SPEC.md:

# 22: INSTALL.md never tells you to clone the repo

Issue: #22. Branch: `22-install-clone-step`.

## TL;DR

INSTALL.md needs a clone step, but the leak gate's first-name rule blocks the
real clone URL. Add the step and a narrow gate exemption for the canonical URL.

## Scope

In:

- Add `git clone https://github.com/<owner>/inkie-deck.git && cd inkie-deck` between sections 1 and 2.
- Narrow leak-gate exemption for the canonical repo URL, with a self-test case proving the name rule still fires elsewhere.
- While the repo is private, a note that `gh auth login` is needed in the Linux environment (delete once public).

Out:

- nothing stated

## Acceptance

- [ ] INSTALL.md has an explicit clone step with the real URL.
- [ ] `pnpm check:leaks` and `--self-test` pass.
- [ ] The install-verification rig extracts and runs the clone block, or deliberately skips it with a comment saying why.

## Test plan

- Run `pnpm check:leaks` and `node scripts/leak-gate.mjs --self-test`.
- Run the install rig and confirm the clone block is run or skipped with a stated reason.

## Decisions log

- Started from issue #22.

## Follow-ups

- none yet

Notes

  • The leak gate's first-name rule matches the maintainer's first name in URLs, so docs use <owner> placeholders (same problem as INSTALL.md never tells you to clone the repo #22).
  • Follow-up, out of scope: mirror these files into the memory-layer repo once this lands.

🤖 Generated with Claude Code

https://claude.ai/code/session_013T1CEPXfL3Zgxes5iMmseX


Generated by Claude Code

Signed-off-by: Simon <simon@inkie.ink>
@simon-inkie
simon-inkie force-pushed the 39-contributor-workflow branch from a85bf34 to d1d4620 Compare October 4, 2026 14:09
…f commits (#39)

Rebased onto main, which now carries CONTRIBUTING.md (from #45). AGENTS.md
and CLAUDE.md are pointers to CONTRIBUTING.md and DEVELOPMENT.md rather than
a second rulebook: the branch-naming, issue-first and DCO rules are stated in
one place only. DEVELOPMENT.md and the start-issue skill now sign off every
commit (git commit -s) and the skill's first commit uses the
type(scope): summary (#issue) style. The SPEC rule is scoped to non-trivial
work, matching CONTRIBUTING.md.

Refs #39

Signed-off-by: Simon <simon@inkie.ink>
@simon-inkie
simon-inkie force-pushed the 39-contributor-workflow branch from d1d4620 to 234f200 Compare October 4, 2026 14:10
@simon-inkie
simon-inkie merged commit 6d1332f into main Oct 4, 2026
4 checks passed
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.

Contributor workflow: AGENTS.md, DEVELOPMENT.md, .specs/ and a start-issue skill

1 participant

0