Landed on almost the same thesis from the requirements side rather than architecture. The thing that unlocked it for me was making the docs both hierarchical and machine-readable — one file per entity (goal / feature / requirement / AC) with YAML frontmatter holding IDs, status, and trace links, committed alongside the code. Colocating is only half the value; the other half is that the AI pipeline can ingest it as structured context instead of free-form prose.
I ended up building a VS Code extension around this called SPECLAN (disclosure: I'm the creator). What makes it click is the MCP server — the spec tree is exposed as tools, so the AI quality gate queries architecture and requirements the same way it queries tests. That's the piece that turned "docs in git" into "docs the gate actually uses."
Your Vertex AI gateway sounds like the natural place this lands — did the agents start quoting architecture doc IDs back in quality findings, or do they still frame concerns in natural language? That's been the hardest part of the loop for me.
Hello @thlandgraf ! It looks like on the screenshot. But as it is the Gemini answer it can be formatted as needed. I'm using critical findings section (blockers) and overall recommendations (non-blockers). This is a bit old screenshot because now it also writes additional info about OWASP. Next week I will share more info about the gate as I'm planning to perform GDG Workshop about it :)
Also it is screenshot from the developer's IDE. I decided to give me (the developer) possibility to run it from the IDE before creating MR to save time :D
Thanks @alexandertyutin — the blockers / non-blockers split is exactly the piece I was missing. Severity-bucketed findings map cleanly to CI logic ("block MR if blockers bucket is non-empty") in a way strict doc-ID quoting never really does, and it's the bit a human reviewer scans first anyway. That's a much nicer forcing function than what I was imagining.
The IDE-before-MR placement is interesting too — do you run it in both places (IDE + pre-merge CI), or did you drop the CI gate once the IDE version was fast enough? I keep hitting the same tension between "fast feedback" and "actually enforced."
Would love to catch the GDG Workshop writeup if you publish slides afterwards. Which region / date are you running it in?
@thlandgraf Thanks for your interest and questions! They really make me thinking deeply about the practical side 🙌
This gate was born during indie-development of a niche product which intended to reach adults and children. So I understood that I was facing huge conflict of interest between CEO, CTO and CISO in my head from the very beginning 😁 Also I have a teammate and understanding that there may be a point in future when additional people will added to the process.
So my first intent was to provide another point of me for any stage of the SDLC. When I'm implementing a new feature I have my code and approach at whole be reviewed by a security guy. And when I'm a security guy I need a developer/architect counterparty. This approach turned me into the process of finding trade-offs.
Other hand I was interested to test this approach of process automation and documenting. I've discovered that there may be interesting side effect as the practically approved approach of bringing required competence into the IDE and CI/CD.
The IDE-before-MR placement is interesting too — do you run it in both places (IDE + pre-merge CI)
Firstly I've added the check into the CI and was happy as CISO. But then I realized as a developer that wait several minutes for the "MR Failed" response it too expensive 😁 So I just cloned the CI step into a bash script and started use the script as a developer (before the final push or just when I feel that I need a fresh eyes). But I haven't removed the CI check because of human aspect (I can forget to check locally) and for possible case of sharing the development process.
And sometime this cross check brings the value 😁 I saw different cases when I forgot to check locally of when the CI check provided additional view. It some kind of a real process modelling when different approvers may provide different details 😁
Also it turned me to use documented security and architecture exceptions with approved compensatory measures and due dates 😂 So I can state the it has definitely improved my development and deploy discipline and provided the scalable part of change management process at the same time.
Would love to catch the GDG Workshop writeup if you publish slides afterwards. Which region / date are you running it in?
We will run it in Russian at 25th of April (this Saturday). Link here. But I plan to prepare repo with code samples and explanatory video. Based on threads here I understand now that I should compile threads and questions into some kind of a supportive demo video and process description. At least for myself 😅 I think I will do it and publish here also 🙌 And maybe additional workshops will be ran in English then...
The CEO/CTO/CISO-in-one-head framing really resonates — I've spent the last 7 years in Head-of-Digitization roles where the same conflict plays out, except spread across actual humans rather than one person. The gate ends up doing the same job in both cases: forcing a structured trade-off conversation that would otherwise happen as a vibes-based argument in a meeting. The artifact becomes the place where the conflict resolves instead of where it starts.
Watching for the English follow-up. Happy to be a second pair of eyes on the workshop materials before the English run if it would help.
Landed on almost the same thesis from the requirements side rather than architecture. The thing that unlocked it for me was making the docs both hierarchical and machine-readable — one file per entity (goal / feature / requirement / AC) with YAML frontmatter holding IDs, status, and trace links, committed alongside the code. Colocating is only half the value; the other half is that the AI pipeline can ingest it as structured context instead of free-form prose.
I ended up building a VS Code extension around this called SPECLAN (disclosure: I'm the creator). What makes it click is the MCP server — the spec tree is exposed as tools, so the AI quality gate queries architecture and requirements the same way it queries tests. That's the piece that turned "docs in git" into "docs the gate actually uses."
Your Vertex AI gateway sounds like the natural place this lands — did the agents start quoting architecture doc IDs back in quality findings, or do they still frame concerns in natural language? That's been the hardest part of the loop for me.
Hello @thlandgraf ! It looks like on the screenshot. But as it is the Gemini answer it can be formatted as needed. I'm using critical findings section (blockers) and overall recommendations (non-blockers). This is a bit old screenshot because now it also writes additional info about OWASP. Next week I will share more info about the gate as I'm planning to perform GDG Workshop about it :)
Also it is screenshot from the developer's IDE. I decided to give me (the developer) possibility to run it from the IDE before creating MR to save time :D
Thanks @alexandertyutin — the blockers / non-blockers split is exactly the piece I was missing. Severity-bucketed findings map cleanly to CI logic ("block MR if blockers bucket is non-empty") in a way strict doc-ID quoting never really does, and it's the bit a human reviewer scans first anyway. That's a much nicer forcing function than what I was imagining.
The IDE-before-MR placement is interesting too — do you run it in both places (IDE + pre-merge CI), or did you drop the CI gate once the IDE version was fast enough? I keep hitting the same tension between "fast feedback" and "actually enforced."
Would love to catch the GDG Workshop writeup if you publish slides afterwards. Which region / date are you running it in?
@thlandgraf Thanks for your interest and questions! They really make me thinking deeply about the practical side 🙌
This gate was born during indie-development of a niche product which intended to reach adults and children. So I understood that I was facing huge conflict of interest between CEO, CTO and CISO in my head from the very beginning 😁 Also I have a teammate and understanding that there may be a point in future when additional people will added to the process.
So my first intent was to provide another point of me for any stage of the SDLC. When I'm implementing a new feature I have my code and approach at whole be reviewed by a security guy. And when I'm a security guy I need a developer/architect counterparty. This approach turned me into the process of finding trade-offs.
Other hand I was interested to test this approach of process automation and documenting. I've discovered that there may be interesting side effect as the practically approved approach of bringing required competence into the IDE and CI/CD.
Firstly I've added the check into the CI and was happy as CISO. But then I realized as a developer that wait several minutes for the "MR Failed" response it too expensive 😁 So I just cloned the CI step into a bash script and started use the script as a developer (before the final push or just when I feel that I need a fresh eyes). But I haven't removed the CI check because of human aspect (I can forget to check locally) and for possible case of sharing the development process.
And sometime this cross check brings the value 😁 I saw different cases when I forgot to check locally of when the CI check provided additional view. It some kind of a real process modelling when different approvers may provide different details 😁
Also it turned me to use documented security and architecture exceptions with approved compensatory measures and due dates 😂 So I can state the it has definitely improved my development and deploy discipline and provided the scalable part of change management process at the same time.
We will run it in Russian at 25th of April (this Saturday). Link here. But I plan to prepare repo with code samples and explanatory video. Based on threads here I understand now that I should compile threads and questions into some kind of a supportive demo video and process description. At least for myself 😅 I think I will do it and publish here also 🙌 And maybe additional workshops will be ran in English then...
The CEO/CTO/CISO-in-one-head framing really resonates — I've spent the last 7 years in Head-of-Digitization roles where the same conflict plays out, except spread across actual humans rather than one person. The gate ends up doing the same job in both cases: forcing a structured trade-off conversation that would otherwise happen as a vibes-based argument in a meeting. The artifact becomes the place where the conflict resolves instead of where it starts.
Watching for the English follow-up. Happy to be a second pair of eyes on the workshop materials before the English run if it would help.
Thanks a lot @thlandgraf 🙌