Enhance SLDD process and SPEC.md support across all skills#2
Enhance SLDD process and SPEC.md support across all skills#2
Conversation
Signed-off-by: Maximillian Arruda <dearrudam@gmail.com>
…ss for SPEC.md outputs
…ecks across all steps. - Added prerequisite checks for Steps 02 to 06 to ensure prior steps are complete and approved before proceeding. - Implemented skip-ahead detection to prevent premature implementation or testing requests. - Updated SPEC.md resume behavior to include violation checks and context extraction for each step. - Clarified objectives, audience, style, and tone for each step to ensure consistency and clarity. - Improved response structure for draft outputs and save flows, emphasizing user approval before file operations. - Ensured that SPEC.md maintains a strict structure, containing only progress checklists and links to step files.
…nce checks across all steps
…ks across all SLDD skills
…files across all steps
… across multiple SKILL.md files
…ltiple SKILL.md files
omatheusmesmo
left a comment
omatheusmesmo
left a comment
There was a problem hiding this comment.
@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.
| Strict behavior (automated / non-interactive mode): | ||
| - If the agent is running in an automated or non-interactive environment (CI, scheduled runs, or when the user asked the agent to auto-commit), enforce a strict rule: refuse to perform any file writes or code generation while relevant implementation paths contain uncommitted changes. Require the working tree to be clean. | ||
|
|
||
| Pre-flight checks and TOCTOU mitigation: |
There was a problem hiding this comment.
TOCTOU , look at you, using fancy words!
| At the start of every SLDD session, before any other action: | ||
|
|
||
| 1. **Read `AGENTS.md`** at the project root (if it exists). | ||
| 2. **Look for an `## SLDD` section** with this format: |
There was a problem hiding this comment.
I don't agree with a specfic section for SLDD in AGENTS.md, since it's a file designated to describe the project structure and some guidelines. Specs should be a ephemeral file or if you want to version the specs on git, it should be unrelated to AGENTS.md if no breaking changes was made in the project architecture.
We need to think that SLDD it's just a kind of SDD, so the developers in a project should be free to try another kind, we don't need to bias LLMs
I also think there is no need to specify which language is used, because this is a personal info, it should be in your global AGENTS.md, think in a Open-Source project, how to keep this info accurate when we have multiple developers from multiple countries?
I think we can just hardcode the specs-dir or instruct the LLM to ask for a dir if the user wants another one. For example:
.specs/feature-name/*.md
Please take a look: https://agents.md/
| - Use `specs-dir` as the root for all spec file paths (e.g. `<specs-dir>/<feature-slug>/SPEC.md`). | ||
| - If the user writes in a different language mid-session, switch to match them and update `AGENTS.md` accordingly. | ||
|
|
||
| ### Language Compliance Check (mandatory before every reply) |
There was a problem hiding this comment.
I think these languages topics are just too much, maybe you can elaborate more your reasons about it, WDY @dearrudam ?
| - If modified implementation files exist and no SPEC.md with Steps 01-03 [x] exists → warn about violation | ||
|
|
||
| 3. **Check for existing SPEC.md:** | ||
| - Run `glob` for `**/SPEC.md` to find existing specs |
There was a problem hiding this comment.
glob works for Unix, but what about windows? Maybe we don't need to specify the tool, LLMs handles this pretty well
|
|
||
| --- | ||
|
|
||
| ## SLDD Process Steps |
There was a problem hiding this comment.
Despite being similar to the previous section, I think we can get rid of this section, maybe the skills metadata is enough.
|
|
||
| For existing codebases, use **sldd-99-existing-codebase-understanding-and-context-summary** after step 01 and before step 02 to ground all design decisions in the current architecture and conventions. Skip for greenfield projects. | ||
|
|
||
| For standardized approval template used by all SLDD skills (01-06), use **sldd-98-approval-helper**. |
There was a problem hiding this comment.
So we are jumping from 34 lines to 191. How many tokens are consumed to just read the first skill, @dearrudam ? And what about generate a full SLDD (01-03) for a sample project?
I'm worried about the context window.
2 participants
This pull request introduces a comprehensive overhaul of the SLDD (Spec Loops Driven Development) process documentation and skill definitions. The changes clarify project bootstrapping, enforce strict gatekeeping between steps, and standardize language and file structure compliance across all SLDD skills. The update ensures robust enforcement of process rules, improves multilingual support, and provides explicit, step-by-step instructions for both users and agents.
Key changes include:
1. Project Settings & Language Compliance (All Skills)
AGENTS.md, extracting thelanguageandspecs-dir, and enforcing their use throughout the session. If missing, the agent prompts for configuration and persists the answers. Every user-facing message and generated file must comply with the resolved language, with mandatory translation and compliance checks before every reply. [1] [2] [3]2. Gate Enforcement & Pre-Flight Checks
3. Standardized Resume and Approval Protocols
SPEC.md, checking for prior progress, and detecting violations (e.g., later steps marked complete when earlier ones are not). After presenting draft output, agents must always prompt for user approval before saving or advancing, and never auto-proceed. Pre-defined replies are required to be translated. [1] [2] [3]4. File Structure and Output Rules
SPEC.mdmust contain only the progress checklist with links to step files (e.g.,01-product-intent-specification.md), never the actual content. Detailed, step-by-step save and verification flows are provided to ensure correct file structure.5. Skill-Specific Draft and Save Flows
These changes significantly improve the clarity, enforceability, and multilingual robustness of the SLDD process, making it easier for both users and agents to follow best practices and maintain high engineering standards.