ai-forge-cli 3.0.1__tar.gz → 3.0.3__tar.gz

{ai_forge_cli-3.0.1/src/ai_forge_cli.egg-info → ai_forge_cli-3.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-forge-cli
-Version: 3.0.1
+Version: 3.0.3
 Summary: Forge V4 architecture context CLI
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{ai_forge_cli-3.0.1 → ai_forge_cli-3.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ai-forge-cli"
-version = "3.0.1"
+version = "3.0.3"
 description = "Forge V4 architecture context CLI"
 readme = "README.md"
 requires-python = ">=3.11"

{ai_forge_cli-3.0.1 → ai_forge_cli-3.0.3/src/ai_forge_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-forge-cli
-Version: 3.0.1
+Version: 3.0.3
 Summary: Forge V4 architecture context CLI
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{ai_forge_cli-3.0.1 → ai_forge_cli-3.0.3}/src/ai_forge_cli.egg-info/SOURCES.txt

@@ -33,6 +33,7 @@ src/cli/resources/skills/forge-hydrate/SKILL.md
 src/cli/resources/skills/forge-hydrate/agents/openai.yaml
 src/cli/resources/skills/forge-review/SKILL.md
 src/cli/resources/skills/forge-review/agents/openai.yaml
+src/cli/resources/skills/forge-schema/FRAMEWORK_REUSE_DRAFT.md
 src/cli/resources/skills/forge-schema/SKILL.md
 src/cli/resources/skills/forge-schema/agents/openai.yaml
 src/cli/resources/skills/forge-security/SKILL.md

{ai_forge_cli-3.0.1 → ai_forge_cli-3.0.3}/src/cli/commands/init.py

@@ -164,6 +164,7 @@ def _scaffold_repository(target_root: Path, system_name: str, system_id: str) ->
     _copy_skills(forge_root)
     _rewrite_skill_references(forge_root)
     _create_surface_skills(target_root, forge_root)
+    _create_github_copilot_context(target_root)
 
 
 def _copy_docs(forge_root: Path) -> None:
@@ -260,6 +261,30 @@ def _create_surface_skill(surface_root: Path, forge_root: Path, skill_name: str)
     target_skill.symlink_to(_relative_symlink_target(surface_root, source_skill), target_is_directory=True)
 
 
+def _create_github_copilot_context(target_root: Path) -> None:
+    github_root = target_root / ".github"
+    instructions_root = github_root / "instructions"
+    prompts_root = github_root / "prompts"
+    instructions_root.mkdir(parents=True, exist_ok=True)
+    prompts_root.mkdir(parents=True, exist_ok=True)
+    _write_text(github_root / "copilot-instructions.md", _copilot_instructions_doc())
+    _write_text(instructions_root / "forge.instructions.md", _copilot_path_instructions_doc())
+    for skill_name in SKILL_DIRS:
+        _create_symlink(
+            prompts_root / f"{skill_name}.prompt.md",
+            target_root / "forge" / "skills" / skill_name / "SKILL.md",
+        )
+
+
+def _create_symlink(link_path: Path, destination: Path) -> None:
+    if link_path.exists() or link_path.is_symlink():
+        if link_path.is_symlink() or link_path.is_file():
+            link_path.unlink()
+        else:
+            shutil.rmtree(link_path)
+    link_path.symlink_to(_relative_symlink_target(link_path.parent, destination), target_is_directory=destination.is_dir())
+
+
 def _relative_symlink_target(link_parent: Path, destination: Path) -> Path:
     return Path(os.path.relpath(destination, start=link_parent))
 
@@ -290,6 +315,34 @@ def _scaffold_gitignore() -> str:
     )
 
 
+def _copilot_instructions_doc() -> str:
+    return """# Forge Instructions
+
+This repository uses Forge V4. Start with `forge/USING_FORGE.md`, then use the
+skills in `forge/skills` in this order:
+
+1. `forge-business`
+2. `forge-schema`
+3. `forge-review`
+4. `forge-security`
+5. `forge-build`
+
+Treat `forge/skills` as the canonical skill source. Agent-specific skill
+surfaces are symlinked back to that directory.
+"""
+
+
+def _copilot_path_instructions_doc() -> str:
+    return """---
+applyTo: "**"
+---
+
+Use the Forge V4 workflow for repository work. Read `forge/USING_FORGE.md`
+before implementation, and prefer the relevant skill in `forge/skills` for the
+current task.
+"""
+
+
 def _print_init_summary(target_root: Path, system_name: str, system_id: str) -> None:
     forge_root = target_root / "forge"
     print(_banner("FORGE INITIALIZED"))

{ai_forge_cli-3.0.1 → ai_forge_cli-3.0.3}/src/cli/resources/skills/forge-build/SKILL.md

@@ -31,6 +31,30 @@ This skill has two modes:
 
 Do not redesign the system here. If implementation proves the system, containers, entities, flows, or security posture are wrong, route the change back through `forge-schema`, `forge-review`, or `forge-security`.
 
+## YAGNI Build Discipline
+
+Forge Build treats lazy as efficient, not careless. Before writing code, stop at
+the first rung that works:
+
+1. Does this behavior need to exist for the selected slice?
+2. Does the repository already have this behavior or a pattern to reuse?
+3. Does the language, framework, browser, database, shell, or platform already do it?
+4. Does an already-installed dependency solve it without new ownership?
+5. Can the slice be implemented as a small direct change?
+6. Only then add new structure, and only the minimum that passes the checks.
+
+Never simplify away trust-boundary validation, data-loss-safe error handling,
+security, accessibility, or explicit Forge contracts. Do simplify away
+speculative abstractions, one-use factories, new configuration, generic helper
+layers, premature extension points, and defensive branches for impossible states.
+
+If a shortcut has a known ceiling, mark it near the code with a `yagni:`
+comment that names the ceiling and upgrade trigger. Example:
+
+```text
+// yagni: linear scan is fine below 1k local items; add indexed lookup if crawl time exceeds 200ms.
+```
+
 ## Decision Log
 
 Read `forge/decisions.yaml` when it exists and use it as build context.
@@ -111,18 +135,20 @@ Before coding:
 3. If a simpler approach exists, say so and prefer it unless it violates the Forge model.
 4. If the request, schema, or code context is unclear, stop and name the ambiguity.
 5. Define success criteria as verifiable checks before implementation.
+6. Name what you are deliberately not building yet.
 
 Workflow:
 
 1. Load the narrow Forge context for the target business action, container flow, container, entity, or component.
 2. Identify the smallest runnable slice and the runtime steps it touches.
-3. Map each touched runtime step to the C3 annotations it needs.
-4. Confirm all implementation files live under the correct `source_root`; adjust schema only when the source-root model is genuinely wrong.
-5. Implement the minimum code needed for the slice.
-6. Add or update C3 annotations in the same code change.
-7. Add or update focused tests.
-8. Run relevant tests and `forge crawl --format json`.
-9. Fix broken references, missing annotations, contract drift, and failed tests before calling the slice complete.
+3. Run the YAGNI ladder against each planned code change.
+4. Map each touched runtime step to the C3 annotations it needs.
+5. Confirm all implementation files live under the correct `source_root`; adjust schema only when the source-root model is genuinely wrong.
+6. Add or update focused tests before or alongside implementation when behavior is non-trivial.
+7. Implement the minimum code needed for the slice.
+8. Add or update C3 annotations in the same code change.
+9. Run relevant tests and `forge crawl --format json`.
+10. Fix broken references, missing annotations, contract drift, and failed tests before calling the slice complete.
 
 The C3 scope map should identify:
 
@@ -149,7 +175,10 @@ Think before coding:
 Keep the implementation simple:
 
 - build no features beyond the selected slice
+- prefer stdlib, platform features, and local helpers before new code
+- add no dependency unless the alternative is meaningfully riskier or larger
 - add no abstractions for single-use code
+- inline one-use wrappers, factories, adapters, and config unless Forge contracts require a boundary
 - add no configurability that was not requested
 - add no defensive error handling for impossible states unless required by the Forge contract
 - if the implementation grows much larger than the behavior warrants, simplify it before moving on
@@ -169,6 +198,8 @@ Drive execution by verifiable goals:
 - for bug fixes, reproduce the bug with a failing test before fixing it when feasible
 - for refactors, establish current behavior before changing structure and verify behavior afterward
 - for multi-step slices, use a short plan where each step has its own verification command or observation
+- leave one runnable check for every non-trivial branch, parser, persistence path, security path, or cross-container contract
+- do not create test helpers until duplication appears or repository conventions already provide them
 
 ## Test Mode
 

{ai_forge_cli-3.0.1 → ai_forge_cli-3.0.3}/src/cli/resources/skills/forge-business/SKILL.md

@@ -74,6 +74,12 @@ Use the `forge.decisions` schema from `SCHEMA_REFERENCE_V4.md`.
 
 ## Workflow
 
+Default to the smallest useful business pass. If the user is exploring a small,
+internal, low-spend, or already-understood idea, produce the quick pass first and
+state what deeper research would add. Use the full workflow only when market,
+pricing, regulation, competitive pressure, or investment risk materially affects
+the decision.
+
 ### 1. Frame The Business Scenario
 
 Clarify:
@@ -213,6 +219,16 @@ constraint. Leave system design to `forge-schema`.
 
 ## Output
 
+For a lean pass, create or update `business-plan.md` with:
+
+- target customer
+- problem or desired gain
+- strongest market signal or evidence gap
+- riskiest assumption
+- smallest useful MVP promise
+- business actions needed for `forge-schema`
+- next decision: proceed, stop, pivot, or research deeper
+
 For a full pass, create or update `business-plan.md` with:
 
 - executive summary

{ai_forge_cli-3.0.1 → ai_forge_cli-3.0.3}/src/cli/resources/skills/forge-review/SKILL.md

@@ -65,6 +65,25 @@ Every finding should include:
 
 If no issues are found, say so clearly and note any residual risk.
 
+## Complexity Review
+
+When reviewing build, schema, or annotation changes, also run a complexity pass:
+
+- `delete`: dead schema, unused annotation, speculative feature, stale option
+- `stdlib`: custom code where the language/platform already provides the behavior
+- `native`: dependency or model construct doing what the runtime, database, browser, or Forge crawler already does
+- `yagni`: abstraction, container, config, helper, flow, or decision record with only one real use
+- `shrink`: same contract or behavior can be represented with fewer files, annotations, or schema elements
+
+Prefer one-line findings:
+
+```text
+path:line: yagni: one-use adapter around a single operation. Inline until a second caller exists.
+```
+
+Do not apply fixes during review unless the user asks for a fix pass. End with a
+rough net impact when useful: `net: -N lines/files/schema elements possible`.
+
 ## Workflow
 
 ### 1. Establish Scope

ai_forge_cli-3.0.3/src/cli/resources/skills/forge-schema/FRAMEWORK_REUSE_DRAFT.md

@@ -0,0 +1,61 @@
+# Framework Reuse Draft
+
+Draft language for `forge-schema`:
+
+Before modeling custom runtime responsibility, classify each required capability
+as core business logic or commodity functionality.
+
+Core business logic is behavior that makes this product meaningfully different:
+domain workflow, proprietary decisioning, unique data model, customer-specific
+operations, or business rules that cannot be delegated without losing the point
+of the system.
+
+Commodity functionality is everything else: authentication, authorization, RAG,
+search, security controls, rate limiting, payments, billing, email, analytics,
+observability, background jobs, queues, file storage, feature flags, admin
+tooling, import/export, notifications, scheduling, and common CRUD scaffolding.
+
+For each commodity capability, propose existing options before designing custom
+code:
+
+- framework-native option
+- managed service option
+- platform primitive option
+- bootstrap or starter framework option when it would remove setup burden
+
+For each option, name:
+
+- responsibility removed from this system
+- smallest native/local alternative
+- integration boundary introduced
+- data ownership or compliance implication
+- cost, lock-in, and operational burden
+- added code, schema, configuration, infrastructure, and operating procedure
+- upgrade trigger from the smallest option
+- whether it should appear as an external dependency, runtime container, or
+  deferred decision
+
+YAGNI hardening:
+
+- Propose frameworks before custom code, but do not adopt them automatically.
+- Prefer the smallest option that satisfies the current build slice.
+- Reject any option that adds unused flows, roles, queues, admin surfaces,
+  multi-tenant models, billing products, deployment units, or configuration.
+- Model a managed/framework capability as an external dependency unless this
+  system deploys, operates, or owns the runtime.
+- Record a decision when custom commodity functionality is chosen or when a
+  reuse option materially shapes architecture.
+
+Useful examples to consider:
+
+- auth: Auth.js, Clerk, Supabase Auth, Django auth, Rails authentication
+- RAG and AI retrieval: LangChain, LlamaIndex, provider/vector-store templates
+- security: OWASP ASVS, Arcjet, framework middleware, platform WAF features
+- rate limiting: Upstash Rate Limit, Arcjet, API gateway or platform limits
+- payments: Stripe Checkout, Stripe Billing, Paddle, provider-hosted checkout
+- bootstrap: next-forge, create-t3-app, Django, Rails, Laravel, Phoenix,
+  framework starters already present in the repository
+
+Do not select a technology because it is popular. Select it only when it reduces
+owned code while preserving the system's business intent, security posture, data
+ownership, deployment model, and build slice.

{ai_forge_cli-3.0.1 → ai_forge_cli-3.0.3}/src/cli/resources/skills/forge-schema/SKILL.md

@@ -97,6 +97,39 @@ Use a consultative system design workshop style.
 7. Prefer the simplest architecture that satisfies the system drivers.
 8. Keep schema tied to real runtime, ownership, security, or operational needs.
 
+## Framework Reuse Preface
+
+Do not reinvent non-core capabilities. For every feature that is not core
+business logic, first identify existing industry-standard frameworks, managed
+services, platform primitives, or bootstrap templates the developer could build
+on. This includes authentication, authorization, RAG, search, security controls,
+rate limiting, payments, billing, email, analytics, observability, background
+jobs, queues, file storage, feature flags, and admin tooling.
+
+Treat framework suggestions as architecture options, not automatic decisions.
+Propose them before modeling custom runtime responsibility. Use custom
+implementation only when the business logic, constraints, compliance posture,
+cost, data ownership, or integration shape clearly justifies owning it.
+
+Keep this pass YAGNI-hardened: a framework is useful only when it reduces owned
+code and operational risk for the current build slice. Do not adopt a framework,
+managed service, starter, queue, worker, database, auth layer, or policy engine
+because a future version might need it. If the current slice can use a local
+framework primitive, existing repository pattern, or simpler managed feature,
+prefer that over a broader platform.
+
+Examples to consider when relevant:
+
+- auth: Auth.js, Clerk, Supabase Auth, framework-native auth
+- RAG and AI retrieval: LangChain, LlamaIndex, vector database integrations
+- security and abuse prevention: OWASP ASVS, Arcjet, platform middleware
+- rate limiting: Upstash Rate Limit, Arcjet, API gateway or platform limits
+- payments and billing: Stripe Checkout, Stripe Billing, Paddle
+- bootstrap frameworks: next-forge, create-t3-app, Django, Rails, Laravel,
+  Phoenix, framework starters already present in the repository
+
+Examples are prompts for research and comparison, not defaults.
+
 ## Description-First Drafting
 
 When the operator asks to evaluate ideas before schema authoring, draft
@@ -139,6 +172,20 @@ Use these lenses to improve judgment. Do not force every insight into YAML.
 
 ## Workflow
 
+Default to the minimum truthful schema pass:
+
+1. system intent and boundary
+2. real actors and external dependencies
+3. business actions that matter now
+4. real runtime containers only where runtime, deployment, ownership, scaling, or
+   security boundaries justify them
+5. business-significant entities only
+
+Add runtime flows, entity lifecycle detail, deployment metadata, and C3
+responsibility plans only when they clarify the first build slice or prevent a
+real design mistake. Do not model future options as if they are current
+architecture.
+
 ### Phase 1: Situation Scan
 
 If Forge files exist, inspect them:
@@ -228,7 +275,36 @@ order_repository
 
 That belongs to code annotations.
 
-### Phase 4: Container Model
+### Phase 4: Capability Reuse Pass
+
+Before finalizing runtime containers or custom responsibilities, classify each
+required capability as either core business logic or commodity functionality.
+
+For commodity functionality, propose existing options:
+
+- one or two framework, managed-service, platform, or bootstrap options
+- the smallest viable local or platform-native option
+- what responsibility the option would remove from this system
+- what new dependency, data boundary, cost, or lock-in it introduces
+- what code, schema, configuration, infrastructure, or operating procedure it
+  would add
+- the concrete trigger that would justify upgrading from the smallest option
+- whether the schema should model it as an external dependency, a container, or
+  a deferred decision
+
+Prefer external dependencies for managed services and framework capabilities
+that the system calls but does not own. Create a container only when this system
+deploys, operates, or meaningfully owns that runtime.
+
+Reject reuse options that add more surface area than the custom or native
+alternative for the current slice. A reusable framework that introduces unused
+flows, roles, queues, admin surfaces, multi-tenant models, billing products, or
+deployment units is still bloat until those responsibilities are real.
+
+Record a decision when choosing to build custom commodity functionality or when
+choosing a framework/service that shapes architecture.
+
+### Phase 5: Container Model
 
 Settle runtime containers after runtime flow speculation.
 
@@ -257,7 +333,7 @@ Rules:
 - Cross-container flow steps describe runtime control movement.
 - Inside-container logic should stay summarized until C3 annotations exist.
 
-### Phase 5: Entity Model
+### Phase 6: Entity Model
 
 Author or refine:
 
@@ -282,7 +358,7 @@ Rules:
 - `persisted_in` should point to durable storage ownership.
 - Do not create entities for incidental DTOs.
 
-### Phase 6: C3 Responsibility Plan
+### Phase 7: C3 Responsibility Plan
 
 For the first build slice, identify what implementation should later annotate:
 
@@ -302,7 +378,7 @@ When building this slice:
 - account_store should become @forge:persistence
 ```
 
-### Phase 7: Validation
+### Phase 8: Validation
 
 After schema edits, run where available:
 
@@ -365,14 +441,20 @@ Before calling schema work complete, check:
 2. Does `system.yaml` describe system intent, not implementation?
 3. Are business actions expressed as intent and outcomes?
 4. Were runtime flows speculated before containers were finalized?
-5. Are containers real runtime units?
-6. Are container responsibilities distinct?
-7. Are central flows cross-container/runtime-level, not C3 internals?
-8. Are entities business-significant?
-9. Are ownership, persistence, and lifecycle separated?
-10. Is C3 intentionally left to annotations?
-11. Is the first build slice thin and buildable?
-12. Would `forge-review` have enough context to evaluate the model?
+5. Were non-core capabilities checked against existing frameworks, managed
+   services, platform primitives, or bootstrap templates?
+6. Did each proposed reuse option beat the smallest native/local option for the
+   current slice?
+7. Were unused framework features, future workflows, speculative services, and
+   premature integration layers excluded from the schema?
+8. Are containers real runtime units?
+9. Are container responsibilities distinct?
+10. Are central flows cross-container/runtime-level, not C3 internals?
+11. Are entities business-significant?
+12. Are ownership, persistence, and lifecycle separated?
+13. Is C3 intentionally left to annotations?
+14. Is the first build slice thin and buildable?
+15. Would `forge-review` have enough context to evaluate the model?
 
 ## Output
 
@@ -381,6 +463,8 @@ When making changes, summarize:
 - files changed
 - system design decisions made
 - runtime flow assumptions
+- framework, managed-service, platform, or bootstrap options considered for
+  non-core functionality
 - container boundaries chosen
 - entities identified
 - C3 responsibilities deferred to annotations
@@ -390,6 +474,7 @@ When not making changes, produce a design brief with:
 
 - recommended system intent
 - inferred business-action/runtime-flow mapping
+- recommended reuse options for non-core capabilities
 - recommended container model
 - recommended entity model
 - key trade-offs
@@ -402,6 +487,11 @@ When not making changes, produce a design brief with:
 - Do not model inside-container flows centrally.
 - Do not over-model.
 - Do not add distributed-system complexity without a concrete driver.
+- Do not invent custom implementations for commodity capabilities before
+  proposing existing framework, platform, managed-service, or bootstrap options.
+- Do not adopt a reuse option that adds more runtime, schema, configuration, or
+  operational surface than the current slice needs.
+- Do not model unused framework capabilities as current architecture.
 - Do not hide uncertainty inside confident YAML.
 - Do not use technology names as architecture justification.
 - Do not proceed to build before schema, security, and review concerns are clear.

{ai_forge_cli-3.0.1 → ai_forge_cli-3.0.3}/src/cli/resources/skills/forge-security/SKILL.md

@@ -162,8 +162,14 @@ Ask only questions that cannot be inferred from the model.
 
 ### 4. Research Medium-Specific Attack Vectors
 
-When reviewing a real system or codebase, research current common attack vectors
-for the system's medium before finalizing findings.
+When reviewing a real system or codebase with meaningful security exposure,
+research current common attack vectors for the system's medium before finalizing
+findings. Meaningful exposure includes public input, authentication,
+authorization, sensitive data, money movement, third-party calls, privileged
+actions, deployment surfaces, or user-controlled persistence/query behavior.
+
+For a small model-only edit outside those areas, do a lightweight trust-boundary
+review and state that attack-vector research was not needed.
 
 Use authoritative public references first, such as:
 

{ai_forge_cli-3.0.1 → ai_forge_cli-3.0.3}/tests/test_context.py

@@ -130,6 +130,10 @@ def test_init_scaffolds_traversable_repo(tmp_path: Path, capsys) -> None:
     assert (root / ".claude" / "skills" / "forge-hydrate").is_symlink()
     assert (root / ".agents" / "skills" / "forge-review").is_symlink()
     assert (root / ".copilot" / "skills" / "forge-security").is_symlink()
+    assert (root / ".github" / "copilot-instructions.md").exists()
+    assert (root / ".github" / "instructions" / "forge.instructions.md").exists()
+    assert (root / ".github" / "prompts" / "forge-build.prompt.md").is_symlink()
+    assert (root / ".github" / "prompts" / "forge-build.prompt.md").resolve() == forge_root / "skills" / "forge-build" / "SKILL.md"
     rewritten_skill = (forge_root / "skills" / "forge-schema" / "SKILL.md").read_text(encoding="utf-8")
     assert "forge/SCHEMA_REFERENCE_V4.md" in rewritten_skill
     assert "forge/USING_FORGE.md" in rewritten_skill