specs: Consolidate AGENTS.md into a single file

Author: zah

.obsidian/workspace.json

@@ -13,12 +13,12 @@
             "state": {
               "type": "markdown",
               "state": {
-                "file": "specs/Public/CLI.md",
+                "file": "specs/AGENTS.md",
                 "mode": "source",
                 "source": false
               },
               "icon": "lucide-file",
-              "title": "CLI"
+              "title": "AGENTS"
             }
           },
           {
@@ -194,10 +194,12 @@
   },
   "active": "01bf72509d2b5652",
   "lastOpenFiles": [
+    "docs/marketing-one-pager.md",
     "specs/AGENTS.md",
+    "specs/Public/AGENTS.md",
+    "specs/Public/CLI.md",
     "scripts/md-mermaid-validate.sh",
     "specs/Public/Configuration.md",
-    "specs/Public/CLI.md",
     "specs/Public/3rd-Party Agents/3rd-Party Agent Description Template.md",
     "specs/Public/Nix Devcontainer/Devcontainer User Setup.md",
     "specs/Public/Nix Devcontainer/Devcontainer Design.md",
@@ -208,7 +210,6 @@
     "specs/Public/Browser Automation/Codex.md",
     "specs/Public/Extras Framework.md",
     "specs/Public/Lima VM Images.md",
-    "specs/Public/AGENTS.md",
     "specs/Public/Agent Time Travel.md",
     "specs/Public/WebUI PRD.md",
     "specs/Public/TUI PRD.md",
@@ -225,7 +226,6 @@
     "test/logs/temp_output_20250828_001209.log",
     "test/temp_test_runner_1756329129.rb",
     "test/logs/test_run_20250828_001209.log",
-    "specs/Initial Developer Input/Configuration.md",
     "specs/Initial Developer Input",
     "specs/Research"
   ]

specs/AGENTS.md

@@ -1,6 +1,20 @@
+This folder contains a work-in-progress specification for the next iteration of the agents-workflow product.
+
+The main ideas of the product are described in the [marketing-one-pager](../../docs/marketing-one-pager.md) document. Please read it.
+
+Currently, the spec is not finalized and we are not ready to start the implementation of the software. The folder `specs/Initial Developer Input` contains files that should be treated as a ground truth for the specification effort. You are expected to work on the markdown files in the `specs/Public` folder, which should detail everything with a much higher precision, but please note that not all information in them has been fully reviewed by the development team yet.
+
+Files in the public folder should never refer to documents in the `specs/Initial Developer Input` folder or the `specs/Research` folder, where we put preliminary-research findings that also haven't been fully vetted.
+
+Your goal is to build a very comprehensive specification, meeting the goals stated in the initial developer input and expanding upon them with solid research and engineering. You may use the information provided in the preliminary research findings, but please verify it, potentially by building a small PoC programs.
+
+The public spec should be a stand-alone document that never references other folders. In other words, your job is to transform the content from the other folders into a high-quality spec.
+
+For each file in the `spec/Public` folder, there will be a corresponding file in the `spec/Implementation Progress` folder. This is a place to store information regarding what was already prototyped or implemented for production use. The files in this folder should contain references to source code files that are a good starting point for someone who wants to see the code behind the spec.
+
+Some of the markdown files have standardized Obsidian headers indicating their current review status. Avoid modifying files with status "Reviewed" or "Final" unless explicitly asked.
 # Specs Maintenance
 
 - Before committing any change to the `specs/` folder, run `just lint-specs` from the project root. This performs Markdown linting, link checking, spell checking, prose/style linting, and Mermaid diagram validation.
-- The Nix dev shell is fully reproducible; if a required tool is missing inside the shell, fix `flake.nix` rather than using ad‑hoc fallbacks.
 
 If the pre-commit hook blocks your commit, run `just lint-specs`, address the reported issues, and commit again.