F-070: design uniform target plugins API

README.md

@@ -45,7 +45,7 @@ systems like Buck and Bazel.
 2. [**JVM getting started**](docs/JVM-GETTING-STARTED.md) — pure JVM tutorial, run the sample, greenfield skeleton with `binary`, `api`/`impl`, target cheat sheet (F-032)
 3. [Sample app gold standard](docs/SAMPLE-APP.md) — multi-feature layout to copy
 4. [Dependency matrix](docs/DEPENDENCY-MATRIX.md) — what may depend on what
-5. [External deps catalogs](docs/DEPS-CATALOG.md) · [Compose](docs/COMPOSE.md) · [Environment](docs/ENV.md)
+5. [External deps catalogs](docs/DEPS-CATALOG.md) · [Target plugins API design](docs/TARGET-PLUGINS.md) (F-070) · [Compose](docs/COMPOSE.md) · [Environment](docs/ENV.md)
 6. [Plugin publish path](docs/PLUGIN-PUBLISH.md) — Portal metadata DSL + release notes (F-016)
 7. [Configuration performance](docs/CONFIGURATION-PERFORMANCE.md) — measure + hot-path guidance (F-017 / GH #106)
 8. [forma-core public API design](docs/forma-core-api.md) — extraction contract for types / restrictions / registry (F-020)

TICKETS.md

@@ -72,6 +72,19 @@ encourages dumping mixed concerns into one bucket. Prefer specific targets.
 | F-062 | done | Reimplement progressive examples / skills without `androidLibrary` | `examples/android/04` + agent skills + README curriculum |
 | F-063 | done | Hard-remove `androidLibrary` target (after consumers migrated) | DSL + `android.library` type/registry/restrictions removed; JVM `library` + AGP feature helper kept; matrix/docs updated |
 
+## P7 — Target plugins API (uniform external plugins)
+
+Replace chain-based `TargetBuilder.withPlugin` / `PluginWrapper` with a **single
+`plugins` argument on every target definition**. Design: `docs/TARGET-PLUGINS.md`.
+Closes the product gap behind GH #36.
+
+| ID | Status | Title | Notes |
+|----|--------|-------|-------|
+| F-070 | done | Design uniform target plugins API + deprecation plan | `docs/TARGET-PLUGINS.md` — Mode 1/2/3 model; `TargetPlugins` / `plugin()`; deprecate chain API; no separate target types by default |
+| F-071 | todo | Implement `TargetPlugins` + wire `plugins` on all Android/JVM target DSLs | `applyTargetPlugins` after features; unit tests; shims keep sample green |
+| F-072 | todo | Migrate sample off `withPlugin`; deprecate `TargetBuilder` / `PluginWrapper` | `Plugins.kt` → `PluginSpec` recipes; binary/safe-args call sites |
+| F-073 | todo | Docs + progressive example + agent skill; close GH #36 | GETTING-STARTED + DEPS-CATALOG Mode 2 vs 3; ladder step |
+
 ## Backlog (lower priority / historical GitHub)
 
 Keep for reference; do not start unless higher tickets done or user prioritizes:
@@ -85,7 +98,7 @@ Keep for reference; do not start unless higher tickets done or user prioritizes:
 - GH #51 Support build types
 - GH #46 New navigation system
 - GH #44/#43 Hybrid targets/config examples
-- GH #36 Docs for external plugins
+- GH #36 Docs for external plugins → **P7 / F-070–F-073** (`docs/TARGET-PLUGINS.md`)
 - GH #126 Target features configuration options
 - GH #111 Gradle project as buildscript classpath
 - GH #103 Java 8+ API on Android API ≤26

docs/DEPS-CATALOG.md

@@ -146,3 +146,5 @@ for the androidx/google surface used across features.
 - Architecture map: [`ARCHITECTURE.md`](ARCHITECTURE.md) §2.4
 - Sample settings: `application/settings.gradle.kts`
 - Sample typed catalogs: `build-dependencies/dependencies/src/main/kotlin/`
+- **Target-declared plugins** (safe-args, Crashlytics, …) are a separate mode from
+  catalog companion-lib apply — design: [`TARGET-PLUGINS.md`](TARGET-PLUGINS.md) (F-070+)

docs/PROGRESS.md

@@ -2,6 +2,23 @@
 
 Newest entries first.
 
+## 2026-07-19 — F-070: target plugins API design
+
+- **Ticket:** F-070 → `done` (design only); **F-071…F-073** `todo` on board (P7)
+- **User ask:** design proper APIs for plugins support; deprecate existing mechanism; uniform plugin configs per target definition; simple = part of target def; complex = single arg config (prefer over new target types)
+- **Branch / PR:** `forma/F-070-target-plugins-design` → base `v2`
+- **Skills/modes:** Hermes design/docs (no Grok Build product coding this slice)
+- **Design:** [`docs/TARGET-PLUGINS.md`](TARGET-PLUGINS.md)
+  - **Mode 1** platform features (`FeatureDefinition`) — unchanged
+  - **Mode 2** catalog dependency-driven plugins (KSP) — unchanged; see DEPS-CATALOG
+  - **Mode 3** target-declared `plugins: TargetPlugins` on **every** target DSL
+  - Deprecate `TargetBuilder.withPlugin` / `withPlugins` + public `PluginWrapper` UX
+  - Complex config stays one arg: `plugin(id) { Extension.… }` + optional deps
+  - Separate target type only when plugin creates a new *role* (not for safe-args/Crashlytics)
+- **Product code:** none this slice
+- **Next:** F-071 implement + wire DSLs
+- **Blockers:** none
+
 ## 2026-07-19 — F-018 close: docs soak + ticket done
 
 - **Ticket:** F-018 → `done` (8.x terminal toolchain; AGP 9 = F-019 only with explicit OK)