Enhance SLDD process and SPEC.md support across all skills

[dearrudam]

This pull request introduces significant improvements to the SLDD (Spec Loops Driven Development) skills repository, focusing on clarifying the purpose and architecture of executable skills, enhancing documentation, and providing better support for local development. The changes make the SLDD process, agent responsibilities, and installation options more explicit and developer-friendly.

Documentation and Process Clarifications:

• Added a new AGENTS.md file that clearly defines the repository's purpose, global agent behavior, limits, and conventions for maintaining SLDD skills.
• Updated README.md to:
  • Emphasize that only executable runtime skills are included in skills/, with no shared runtime helpers. [1] [2]
  • Provide a detailed mermaid flowchart and descriptions for each step, including new guidance for brownfield (existing codebase) and greenfield projects.
  • Clarify installation instructions, distinguishing between runtime and development workflows. [1] [2] [3]
  • Update process steps, approval protocols, and artifact handling for better gate enforcement and clarity. [1] [2]

Development Tooling:

• Added install-sldd-skills.sh, a script for local development that installs SLDD skills as symbolic links, enabling immediate visibility of changes in development environments.
  • The script safely cleans up existing links/directories and provides a summary of its actions.

Skill Content Consistency:

• Overhauled skills/sldd-00-process-overview-and-navigation-guide/SKILL.md to:
  • Clearly state objectives, artifact/resume rules, and step routing logic.
  • Provide explicit handling for brownfield/greenfield flows and interrupted execution.
  • Specify approval protocols and response formats for navigation.

Summary of Most Important Changes:

1. Documentation and Process Architecture

• Added AGENTS.md to define agent responsibilities, limits, and conventions.
• Updated README.md with a mermaid flowchart, explicit runtime skill architecture, improved installation/dev instructions, and clarified process flows for brownfield and greenfield projects. [1] [2] [3] [4] [5]

2. Development Workflow Support

• Introduced install-sldd-skills.sh for symlink-based local development, allowing immediate reflection of skill edits in development tools.

3. Skill File Consistency and Navigation

• Rewrote sldd-00-process-overview-and-navigation-guide/SKILL.md to enforce step order, artifact handling, resume logic, and approval protocols.

These changes collectively improve the maintainability, clarity, and usability of the SLDD skills repository for both users and contributors.

[omatheusmesmo]

@dearrudam , great job, man!

I can see how much effort you put on this, I would love to discuss each skill on a Discord call, but I don't think will be easier rather than do this async,

Let's discuss and define a standard to SLDD-00, then we can discuss the remains.

[omatheusmesmo]

Review: sldd-88 over-centralization breaks the self-contained model

Core Problem

sldd-88 became a god-skill that every other skill depends on for gates, save decisions, templates, and section headings. This creates two failures:

1. Runtime coupling — Skills are loaded one-at-a-time. An agent running sldd-01 does NOT have sldd-88 in context. The instruction "refer to Step 88 Section 6" is a dead link at execution time.
2. Semantic loss — Headings without guardrails are structure without substance. "Architecture Diagram" is a heading. "Do not generate implementation code or tests" is a guardrail. They are not interchangeable.

Anti-Patterns

Anti-Pattern	Where	Why It's a Problem
Guardrails replaced by headings	Steps 01–06, 99	Section headings describe what to write, not how to behave. "Do not generate code" is gone from Step 02. Edge-case requirement is gone from Step 01. Version policy specifics are gone from Step 03.
Cross-skill reference as instruction	Every skill: "Use sldd-88 for shared gates, save decision, and templates"	If sldd-88 is not loaded, the skill is non-functional. Self-contained > DRY.
Independence Rule that contradicts reality	sldd-88 Sec 0: "skills are self-contained"	Every skill depends on sldd-88. The rule is false as written.
Two-Phase Verification scope too broad	sldd-88 Sec 4: "every technical step"	Steps 01–03 and 06 produce markdown specs — they don't "modify the codebase." Over-engineering specification steps with action plans.
Gate rules in two places	sldd-88 Sec 3 + each skill's "Gate + Resume Checks"	Duplicated = drift risk. Edit one, forget the other.

Proposal

Delete sldd-88 and sldd-98. They create coupling that costs more than the duplication they save.

Content from sldd-88/98	Should live in	Reason
SPEC.md journal template	sldd-00	It's the orchestrator — it creates the SPEC.md
Artifact directory structure	sldd-00	Same reason
Gate order	sldd-00	Already has this
Behavioral guardrails	Each skill	"Do not generate code", "edge case per criterion", version policy specifics — these guide agent behavior, not file structure
Section headings with guidance	Each skill	Headings + per-heading substance, not bare names
Gate prerequisites	Each skill	The skill is the authoritative source
Save flow	Each skill (1 paragraph)	"Present draft → wait for approval → save artifact → mark [x] in SPEC.md → ask to continue"
Two-Phase Protocol	sldd-04 and sldd-05 only	Only implementation steps need action-plan-then-evidence
Approval prompts	Each skill (inline)	Standardizing exact prompt wording doesn't justify an 83-line skill dependency

Result

7 self-contained skills, zero cross-skill dependencies, guardrails back where they matter.

Also Missing

• "Existing codebase" is never defined — add a one-line definition in sldd-00
• No revision protocol — if Step 03 reveals Step 01 was insufficient, there's no way to mark a step as under revision, re-approve, and re-validate downstream
• README.md will be stale — if sldd-88/98 stay, they must appear in the skills table

---

made with ☕ by @omatheusmesmo and @glm-5.1