Try openspec: https://github.com/Fission-AI/OpenSpec/blob/main/docs/gettin...

Yesterday I heard about lat.md [1] which seems to have similar ideas about annotating code with spec refs. I now need to try them both.

[1] https://www.lat.md/

Small advice - make one repo “main” and link to it from the website instead of an organisation.

I wanted to star the project to track the progress but it feels a bit weird.. Which repo shall I track? Server? Cli? Sounds like a misc repos.

There are also Architectural Decision Records (ADRs), which might be something similar. https://adr.github.io/

> We are entering the post-slop era. My software is more robust, better tested, better integrated, and more observable than ever before. And my velocity keeps increasing!

Don't we just love the hard fact conclusions based on sample size N=1 and hand-waving arguments?

I’m building something similar with https://github.com/LabLeaks/special (apologies for the desultory slop-laden README, need to give that a lot more human attention) but I’ve gone in a slightly different direction: a “spec” is a product contract claim supported by attached tests that verify it. It’s a little Cucumber-y, if anyone remembers that, but a lot more flexible — you just write stuff like

  @spec LINT_COMMAND.ORPHAN_VERIFIES

  linter reports blocks that do not attach to a supported owned item.

Then

  #[test]
  // @verifies SPECIAL.LINT_COMMAND.ORPHAN_VERIFIES

  fn rejects_orphan_verifies_blocks() {
    let block = block_with_path("src/example.rs", &["@verifies EXPORT.ORPHAN"]);

    let parsed = parse_current(&block);

    assert!(parsed.verifies.is_empty());
    assert_eq!(parsed.diagnostics.len(), 1);
    assert!(
        parsed.diagnostics[0]
            .message
            .contains("@verifies must attach to the next supported item")
    );

}

And then the CLI command “special specs” pulls your specs and all attached verification + test code so you (or your LLM) to analyze whether the (hopefully passing!) test actually supports the product claim.

There’s also a bunch of other code quality commands and source annotations in there for architectural design & analysis, fuzzy-checking for DRY opportunities, and general codebase health. But on the overall principle, this article is dead-on: when developing with LLMs, your source of truth should be in your code, or at least co-located with it.

I also have started numbering my Acceptance criteria and pushing that across the team(s). It’s going pretty well. Some note however are

1. Don’t write in yaml. It’s really hard for humans. Write in markdown and use a standard means to convert to lists / yaml.

2. Think beyond you writing your own specs - how does this expand into teams of tens or more. The ticketing system you have (jira? Bugzilla) is not designed for discussion of the acceptance criteria. I think we are heading into a world of waterfall again where we have discussions around the acceptance criteria. This is not a bad thing - is used to be called product management and they would write an upfront spec.

If this new world of a tech and a business user lead the writing of a new spec (like a PEP) and then then AI implements it and it’s put into a UAT harness for larger review and a daily cycle begins, we might have something.

Good luck

the token usage isn’t sustainable. formal english is a barrier but requirement for specification. brevity is the language of money and that’s the premise of management using ai.

fyi language alone can’t define/describe requirements which is why UML existed.

ugh with the "maxxing" everything

Stopped at "Specsmaxxing".