Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

[feat] contribute --namespace, to file a learning under one of the namespaces a directory reads

Closed
  • Is something wrong?
#916 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@zszz3 is already working on this.

Since Oct 4, 2026.

  • #979 by @zszz3 — open
  • #980 by @yudongyouqing — open

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
52/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
typescript
Domain
cli, documentation

Research direction

Start with src/contribute.ts:23-29 to understand the current namespace selection, then read src/projects.ts:233-238 and the existing projects list output. Trace the related updates through skill-data/share/SKILL.md and the regenerated skill-data/core/references/commands.md. Done when contribute accepts only readable namespaces, projects list explains the default and accepted values, and the share instructions use that information.

Written by the indexing model from the issue text.

Description

enhancement

Problem

A directory that reads both its repo's and a group's learnings can't choose either when it contributes. With learnings: [svc-a, payments] on project svc-a, recall in svc-a returns entries from learnings/payments/, and contribute there writes to the shared root, because two namespaces make ownership ambiguous (src/contribute.ts:23-29).

manifest/projects.yaml    svc-a: learnings [svc-a, payments]    svc-b: learnings [svc-b, payments]

in svc-a (0.22.0)
  recall narwhal          learnings/payments/narwhal-contract.md       reads the group      works
  contribute              Contributed: learnings/svc-a-retry-key-…md   the shared root      neither svc-a nor payments

A team that adds a group namespace to share learnings between projects loses each project's own namespace for new learnings, and, in this setup, neither svc-a nor svc-b can target the group without changing its selection or the manifest. Skills and docs don't have this problem, because delivery takes the union of the namespaces. The same manifest delivered payments-skill and docs/payments/ to svc-a.

Proposed Solution

An option on the existing command:

contribute                        unchanged: one active learnings namespace → learnings/<ns>/, none or several → learnings/
                                  with several, it also lists them: "pass --namespace <ns> to file it under one"
contribute --namespace payments   learnings/payments/, if payments is one of the learnings namespaces the directory reads
                                  otherwise it stops and lists the ones it can use
  • Nothing changes for a team that doesn't pass the flag. A team without learnings namespaces has nothing to pass, and every learning keeps going to the shared root.
  • The flag only accepts a namespace the directory already reads, so a learning can't land where its author's recall would not find it. In a workspace as #913 proposes it, that is its delivered selection.
  • A namespace need not match its project's id. A project alpha with learnings: [alpha-notes] (src/projects.ts:233-238) takes --namespace alpha-notes.
  • learnings in the manifest stays one list, with no new key.
  • teamai projects list also prints where contribute writes by default in this directory and which namespaces --namespace accepts, next to the line it already prints (Your active projects (this directory): svc-a):
$ teamai projects list          (in svc-a, with learnings [svc-a, payments])
...
Your active projects (this directory): svc-a
Contributes to: learnings/ (shared root)   --namespace accepts: svc-a, payments
  • The share skill reads that line instead of working the destination out. Today its step 4 only says teamai contribute --file <path> --title "<title>":
 skill-data/share/SKILL.md
-4. **Push it to the team**: run `teamai contribute --file <path> --title "<title>"`
+4. **Pick the namespace**: run `teamai projects list` in the directory you worked in. It prints where `contribute`
+   writes by default and which namespaces `--namespace` accepts. Keep the default when it matches the code the
+   learning is about; otherwise pass the accepted namespace that does. Done when you hold that directory and
+   either the default or one accepted namespace.
+5. **Push it to the team**: in that directory, `teamai contribute --file <path> --title "<title>" [--namespace <ns>]`
 Important
-- Run this as a **sub-agent** (Agent tool) to avoid polluting the main session's context
+- Run this as a **sub-agent** (Agent tool) to avoid polluting the main session's context, and give it the
+  directory you worked in, since a sub-agent starts in the session's directory
-- The document is pushed to the team repo's `teamai-learnings` branch, under `learnings/`, with no pull request
+- The document is pushed to the team repo's `teamai-learnings` branch, with no pull request
  • skill-data/core/references/commands.md is regenerated from the command table for the new flag.

Alternatives Considered

  • Write to the first listed namespace. It changes where existing teams' learnings go, and the order of a YAML list would start to matter without saying so.
  • A separate read-only list in the manifest (for example readLearnings: [payments]). It fixes the default case, but it needs a new manifest key and still gives no way to write into the group.
  • Per-learning targets in frontmatter (projects: [svc-a, svc-b]), with the index filtering on them. More flexible, but it changes the learnings format and the index for what a namespace already expresses.
  • --project <id>, mapped to that project's learnings namespace. Project ids are more familiar than namespaces, but it fails the case above. --project svc-a still resolves to svc-a and payments, so the learning would stay ambiguous, and a group such as payments has no project id to pass. --project also means the active projects on init, not a destination.

Additional Context

Checked with 0.22.0 in a sandbox with the manifest above. pull in svc-a delivered payments-skill, docs/payments/contract.md and docs/svc-a/runbook.md. recall narwhal returned learnings/payments/narwhal-contract.md from the teamai-learnings branch. contribute wrote learnings/svc-a-retry-key-…md to the root.

Found while working on #913. Under #913's proposed workspace model, a workspace's delivered selection includes every child's namespaces, so the same flag would let a learning go to a child's or a group's namespace from the workspace, without cd into the child. #913's Learnings note has the full contract for children and workspaces, with and without this flag. Related to #375, which introduced project learnings namespaces.

Open question: is --namespace the right name for the flag, or would another name read better on contribute?

Dominant language
TypeScript
Stars
5.5k
Forks
443
Avg merge
20h 24m
Merged PRs (30d)
328

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Tencent/teamai-cli

All issues in Tencent/teamai-cli

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.