Skip to content

Commit 8670526

Browse files
tikazyqtikazyq
authored
Merge pull request #1 from codervisor/migrate-prs-66-69
Migrate prs 66 69
2 parents 0f0522f + 7e934e9 commit 8670526

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

59 files changed

+3058
-381
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,4 @@ yarn-debug.log*
2020
yarn-error.log*
2121

2222
.turbo
23+
.vercel

‎blog/2025-11-10-ai-agent-performance.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -271,7 +271,7 @@ LeanSpec is a context engineering methodology for human-AI collaboration on soft
271271
**Learn more**:
272272
- GitHub: [github.com/codervisor/lean-spec](https://github.com/codervisor/lean-spec)
273273
- Docs: [lean-spec.dev](https://lean-spec.dev)
274-
- Research: [Context Engineering Guide](/docs/guide/context-engineering)
274+
- Research: [Context Engineering Guide](/docs/advanced/context-engineering)
275275

276276
**References**:
277277
- [Databricks: Long-Context RAG Performance](https://www.databricks.com/blog/long-context-rag-performance-llms)

docs/guide/ai-agent-memory.mdx renamed to docs/advanced/ai-agent-memory.mdx

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
id: 'ai-agent-memory'
33
title: 'AI Agent Memory'
4-
sidebar_position: 4
4+
sidebar_position: 5
55
---
66
# AI Agent Memory
77

@@ -169,7 +169,7 @@ Like human memory, spec memory requires maintenance:
169169
- Archive completed work (compress to summary)
170170

171171
### Consolidation (Prevent Bloat)
172-
- Apply [Context Engineering](/docs/guide/context-engineering) strategies
172+
- Apply [Context Engineering](/docs/advanced/context-engineering) strategies
173173
- Partition large specs (>400 lines)
174174
- Compact redundant content
175175
- Compress historical phases
@@ -207,4 +207,4 @@ When AI agents can reliably access past decisions, understand rationale, and bui
207207

208208
---
209209

210-
**Related**: Learn about [Context Engineering](/docs/guide/context-engineering) for managing memory size, or explore [MCP Integration](/docs/reference/mcp-server) for the technical implementation of memory retrieval.
210+
**Related**: Learn about [Context Engineering](/docs/advanced/context-engineering) for managing memory size, or explore [MCP Integration](/docs/reference/mcp-server) for the technical implementation of memory retrieval.

docs/guide/context-engineering.mdx renamed to docs/advanced/context-engineering.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
id: 'context-engineering'
33
title: 'Context Engineering'
4-
sidebar_position: 3
4+
sidebar_position: 4
55
---
66
# Context Engineering
77

@@ -320,4 +320,4 @@ Context engineering is **the #1 job** when building with AI. These aren't just o
320320

321321
---
322322

323-
**Related**: See [First Principles](/docs/guide/first-principles) for the foundational constraints, or explore [Sub-Spec Files](/docs/guide/usage/essential-usage/spec-structure#sub-spec-files) for practical implementation of partitioning.
323+
**Related**: See [First Principles](/docs/advanced/first-principles) for the foundational constraints, or explore [Sub-Spec Files](/docs/guide/usage/essential-usage/spec-structure#sub-spec-files) for practical implementation of partitioning.

docs/guide/first-principles.mdx renamed to docs/advanced/first-principles.mdx

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,18 @@
11
---
22
id: 'first-principles'
33
title: 'First Principles'
4-
sidebar_position: 2
4+
sidebar_position: 3
55
---
66
# First Principles
77

88
> "These aren't principles we chose—they're constraints we discovered."
99
1010
From three immutable constraints (physics, biology, economics), five first principles emerge. They define what LeanSpec IS at its core and guide all decisions.
1111

12+
:::info Terminology Note
13+
Terms like **Context**, **Tokens**, **Signal-to-Noise** are defined in [Terminology](/docs/guide/terminology). This page explains the principles built on those terms.
14+
:::
15+
1216
## The Constraints We Discovered
1317

1418
LeanSpec is built on three unchangeable constraints:
@@ -278,4 +282,4 @@ Apply them in priority order. When in doubt, Context Economy always wins.
278282
279283
---
280284
281-
**Next**: Explore [Context Engineering](/docs/guide/context-engineering) to see how these principles are applied programmatically, or learn about [Philosophy & Mindset](/docs/guide/philosophy) for the broader mental models.
285+
**Next**: Explore [Context Engineering](/docs/advanced/context-engineering) to see how these principles are applied programmatically, or learn about [Philosophy & Mindset](/docs/advanced/philosophy) for the broader mental models.

docs/guide/limits-and-tradeoffs.mdx renamed to docs/advanced/limits-and-tradeoffs.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
id: limits-and-tradeoffs
33
title: Limits, Trade-offs & What's Realistic
4-
sidebar_position: 4
4+
sidebar_position: 7
55
---
66

77
# Limits, Trade-offs & What's Realistic
@@ -221,7 +221,7 @@ But: _"Does formalizing intent into a spec add value for this specific work?"_
221221

222222
- [The AI Bubble Article](https://hyperdev.matsuoka.com/p/is-ai-a-bubble-i-didnt-think-so-until) - The critique that sparked this assessment
223223
- [Rice's Theorem Explained](https://www.marvinzhang.dev/blog/rices-theorem-why-automated-testing-will-fail) - Why human involvement is mathematically necessary
224-
- [LeanSpec First Principles](/docs/guide/first-principles) - Our philosophy derived from constraints
224+
- [LeanSpec First Principles](/docs/advanced/first-principles) - Our philosophy derived from constraints
225225
- [When NOT to Use Specs](/docs/guide/usage/ai-assisted/writing-specs-with-ai#when-not-to-use-specs) - Honest guidance on skipping specs
226226

227227
---

docs/guide/philosophy.mdx renamed to docs/advanced/philosophy.mdx

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
---
22
id: 'philosophy'
33
title: 'Philosophy & Mindset'
4-
sidebar_position: 5
4+
sidebar_position: 6
55
---
66
# Philosophy & Mindset
77

88
> "LeanSpec is a mindset, not a format."
99
10-
Beyond the [First Principles](/docs/guide/first-principles), effective LeanSpec practice requires adopting key mental models and beliefs about how specs should work.
10+
Beyond the [First Principles](/docs/advanced/first-principles), effective LeanSpec practice requires adopting key mental models and beliefs about how specs should work.
1111

1212
## Mental Models for AI Co-Creation
1313

@@ -301,4 +301,4 @@ If your specs help people (and AI agents) build better software faster, you're d
301301

302302
---
303303

304-
**Next**: Explore practical day-to-day techniques in [Writing Specs AI Can Execute](/docs/guide/usage/ai-assisted/ai-executable-patterns), or learn [When to Use](/docs/guide/understanding#when-to-use-leanspec) LeanSpec.
304+
**Next**: Explore practical day-to-day techniques in [Writing Specs AI Can Execute](/docs/guide/usage/ai-assisted/ai-executable-patterns), or learn [When to Write Specs](/docs/guide/what-is-leanspec#when-to-write-a-spec) in LeanSpec.

‎docs/comparison.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -299,7 +299,7 @@ A [critical assessment by Robert Matsuoka](https://hyperdev.matsuoka.com/p/is-ai
299299
- Progressive Disclosure (start simple, add structure only when needed)
300300
- Focus on intent that ages well, not exhaustive implementation
301301

302-
📖 [Deep dive: Limits, Trade-offs & What's Realistic →](/docs/guide/limits-and-tradeoffs)
302+
📖 [Deep dive: Limits, Trade-offs & What's Realistic →](/docs/advanced/limits-and-tradeoffs)
303303

304304
---
305305

0 commit comments

Comments
 (0)